{"id":13550050,"url":"https://github.com/mmcc007/sylph","last_synced_at":"2025-08-19T22:06:58.127Z","repository":{"id":42188095,"uuid":"176024023","full_name":"mmcc007/sylph","owner":"mmcc007","description":"Runs Flutter integration tests on real devices in cloud.","archived":false,"fork":false,"pushed_at":"2022-10-06T05:44:07.000Z","size":5680,"stargazers_count":157,"open_issues_count":40,"forks_count":45,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-16T16:07:26.987Z","etag":null,"topics":["aws-devicefarm","ci-cd","flutter","flutter-demo","flutter-test","integration-testing"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mmcc007.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-16T20:57:31.000Z","updated_at":"2024-02-04T07:44:24.000Z","dependencies_parsed_at":"2022-09-14T04:01:04.814Z","dependency_job_id":null,"html_url":"https://github.com/mmcc007/sylph","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmcc007%2Fsylph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmcc007%2Fsylph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmcc007%2Fsylph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmcc007%2Fsylph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmcc007","download_url":"https://codeload.github.com/mmcc007/sylph/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231940632,"owners_count":18449187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-devicefarm","ci-cd","flutter","flutter-demo","flutter-test","integration-testing"],"created_at":"2024-08-01T12:01:28.453Z","updated_at":"2024-12-31T21:58:59.143Z","avatar_url":"https://github.com/mmcc007.png","language":"Dart","funding_links":[],"categories":["Dart"],"sub_categories":[],"readme":"[![pub package](https://img.shields.io/pub/v/sylph.svg)](https://pub.dartlang.org/packages/sylph) \n[![Build Status](https://travis-ci.com/mmcc007/sylph.svg?branch=master)](https://travis-ci.com/mmcc007/sylph)\n[![Build status](https://ci.appveyor.com/api/projects/status/ua5hg82feg6aabsd/branch/master?svg=true)](https://ci.appveyor.com/project/mmcc007/sylph/branch/master)\n[![codecov](https://codecov.io/gh/mmcc007/sylph/branch/master/graph/badge.svg)](https://codecov.io/gh/mmcc007/sylph)\n\n\u003ca href=\"https://dlpng.com/png/3962939\"\u003e\u003cimg src=\"art/sylph_logo.png\" width=\"30%\" title=\"Click for source\" alt=\"Sylph\"\u003e\u003c/a\u003e\n\n_A sylph is a mythological invisible being of the air._\n[Wikipedia](https://en.wikipedia.org/wiki/Sylph)\n\n# _Sylph_\n_Sylph_ is a command line utility for running Flutter integration and end-to-end tests on pools of real iOS and Android devices in the cloud. _Sylph_ runs on mac, linux and windows and also in a CI environment. \n\n_Sylph_ works with AWS Device Farm for up to hundreds of Android and iOS devices in a single run.\n\n# Installation\n```\npub global activate sylph\n```\n\n# Usage\n```\nsylph\n```\nor, if not using the default config file:\n```\nsylph -c \u003cpath to config file\u003e\n```\n\nGeneral usage:\n```\nusage: sylph [--help] [--config \u003cconfig file\u003e] [--devices \u003call|android|ios\u003e] [--verbose]\n\nsample usage: sylph\n\n-c, --config=\u003csylph.yaml\u003e          Path to config file.\n                                   (defaults to \"sylph.yaml\")\n\n-d, --devices=\u003call|android|ios\u003e    List devices available in cloud.\n                                   [all, android, ios]\n\n-v, --verbose                      Noisy logging, including all shell commands executed.\n-h, --help                         Display this help information.\n```\n\n# Dependencies\n## AWS CLI\nInstall AWS Command Line Interface (AWS CLI)\n\nMacOS/Linux:\n```\ncurl \"https://s3.amazonaws.com/aws-cli/awscli-bundle.zip\" -o \"awscli-bundle.zip\"\nunzip awscli-bundle.zip\nsudo ./awscli-bundle/install -i /usr/local/aws -b /usr/local/bin/aws\n``` \n\nWindows:\n```\npip install  awscli \n```\n\nFor alternative install options see:  \nhttps://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html\n\n## AWS CLI Credentials\nConfigure the AWS CLI credentials:\n```\n$ aws configure\nAWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE\nAWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\nDefault region name [None]: us-west-2\nDefault output format [None]: json\n```\nFor alternative configuration options see:  \nhttps://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html\n\n## Test AWS CLI\nConfirm AWS CLI is installed and configured correctly by running an AWS command. For example, the following command should generate output:\n```\naws devicefarm list-projects\n```\n\n# Configuration\nConfiguration information is passed to _Sylph_ using a configuration file. The default config file is called `sylph.yaml`:\n```yaml\n# Config file for Flutter tests on real device pools.\n# Auto-creates projects and device pools if needed.\n# Configures android and ios test runs.\n# Builds app, uploads and runs tests.\n# Then monitors tests, returns final pass/fail result and downloads artifacts.\n# Note: assumes the 'aws' command line utility is logged-in.\n# Note: to build the debug iOS app, certain environment variables are required.\n\n# sylph config\ntmp_dir: /tmp/sylph\nartifacts_dir: /tmp/sylph_artifacts\n# local timeout per device farm run\nsylph_timeout: 720 # seconds approx\n# run on ios and android pools concurrently (for faster results)\nconcurrent_runs: true\n\n# device farm config\nproject_name: App Integration Tests\ndefault_job_timeout: 10 # minutes, set at project creation\n\ndevice_pools:\n\n  - pool_name: android pool 1\n    pool_type: android\n    devices:\n      - name: Google Pixel 2\n        model: Google Pixel 2\n        os: 8.0.0\n\n  - pool_name: ios pool 1\n    pool_type: ios\n    devices:\n      - name: Apple iPhone X\n        model: A1865\n        os: 11.4\n\ntest_suites:\n\n  - test_suite: example tests 1\n    main: test_driver/main.dart\n    tests:\n      - test_driver/main_test.dart\n    pool_names:\n      - android pool 1\n      - ios pool 1\n    job_timeout: 15 # minutes, set per job, over-rides default job timeout above\n\n```\nMultiple test suites, consisting of multiple tests, can be run on each device in each device pool. The 'main' app must include a call to `enableFlutterDriverExtension()`. \n\nDevice pools can consist of multiple devices. Devices in a device pool must be of the same type, iOS or Android.\n\nNote: If running on linux or windows, tests can only be run on Android devices. To run tests on both Android and iOS use a mac CI provider.\n\n## Building an iOS debug app\nTo build a testable iOS app locally, that can run on any real device in the cloud, the following environment variable must be present:\n\n- TEAM_ID  \nThis is the Developer Portal Team ID. It is of the form 'ABCDEFGHIJ'.\n\nA check is made before the start of a run to confirm this environment variable is present.\n\nNote: if not running on an iOS pool this environment variable is not required.\n\n## Populating a device pool\nTo add devices to a device pool, pick devices from the list provided by\n```\nsylph -d android\nor\nsylph -d ios\n```\nand add to the appropriate pool type in sylph.yaml. The listed devices are devices currently available on Device Farm.\n\n## Configuration Validation\nThe sylph.yaml is validated to confirm the devices are  available on Device Farm and tests are present before starting a run. \n\nIf running on an iOS pool, the iOS-related environment variables must be defined. \n\n## Configuring Flavors\nA reference flavor app can be found in [example/flavors](example/flavors). It is taken from https://github.com/flutter/flutter/tree/master/dev/integration_tests/flavors and works for android and iOS. It is currently recommended that you follow this pattern when implementing flavors in your app.\n\nTo enable testing on a flavor add the following to your sylph.yaml:\n```\nflavor: \u003cname of flavor\u003e\n```\n\n# Configuring a CI Environment for _Sylph_\nIn addition to running from the command line, _Sylph_ also runs in a CI environment.\n\n## AWS CLI Credentials for CI\nThe following AWS CLI credentials are required in a CI environment:\n- AWS_ACCESS_KEY_ID\n- AWS_SECRET_ACCESS_KEY\n\nFor details on other credentials see:  \nhttps://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html\n\n## iOS builds\nTo build the iOS app, the provisioning profile and certificate must be installed on the CI build machine. To install these dependencies, Fastlane's match is used. _Sylph_ will detect it is running in a CI environment (using the 'CI' environment variable), and will install fastlane and fastlane scripts. The scripts  are used to install the dependencies using Fastlane's match. The iOS build can then complete as normal.\n\nThe following environment variables are required by a CI build to use Fastlane match:\n- PUBLISHING_MATCH_CERTIFICATE_REPO  \nThis is the location of the private match repo. It expects an ssh-based url. For example, ssh://git@private.mycompany.com/private_repos/match.git  \n- MATCH_PASSWORD  \nThis is the password that was used to encrypt the git repo's contents during match setup.\n\nFor details on how to setup Match see:  \nhttps://docs.fastlane.tools/actions/match/\n\nThe following are required by sylph in a CI environment to connect to the match host. The match host is running a ssh server that connects to the git server which serves the match repo. This configuration is required so that PUBLISHING_MATCH_CERTIFICATE_REPO will work via ssh:\n- SSH_SERVER  \nThis is used to configure the CI's ssh client to find the match host. For example, private.mycompany.com.\n- SSH_SERVER_PORT  \nThis is used to configure the CI's ssh client to find the match host's ssh port. For example, 22.\n\nAs with running from the command line, the following environment variable is also required by _Sylph_ in a CI environment:\n- TEAM_ID  \nThis is the Developer Portal Team ID. It is of the form 'ABCDEFGHIJ'.\n\nNote: if not running on an iOS pool all iOS-related environment variables are not required.\n\n## Sample environment variables for Travis-CI\nFor example, when _Sylph_ is run on Travis-CI the following environment variables are used:\n\n![secret variables](art/travis_env_vars.png)\n\nSee [.travis.yml](.travis.yml) for running _Sylph_ on Travis-CI.\n\nNote: the Travis-CI build uses pre-configured AWS CLI values in [.aws/config](.aws/config).\n\n# Upgrade\nTo upgrade, simply re-issue the install command\n````bash\n$ pub global activate sylph\n````\nTo check the version of _Sylph_ currently installed:\n```\npub global list\n```\n# Live demo\nTo see _Sylph_ in action in a CI environment, a  demo of the [example](example) app is available.  \n\nThe log of the live run on mac and linux is here:  \nhttps://travis-ci.com/mmcc007/sylph\n\nThe resulting artifacts are here:  \nhttps://github.com/mmcc007/sylph/releases  \n(includes a video of test running on device)\n\nTo view a similar run on windows:  \nhttps://ci.appveyor.com/project/mmcc007/sylph\n\n# Contributing\nWhen contributing to this repository, please feel free to discuss via issue or pull request.\n\n[Issues](https://github.com/mmcc007/screenshots/issues) and [pull requests](https://github.com/mmcc007/screenshots/pulls) are welcome.\n\nYour feedback is used to guide where development effort is focused. So feel free to create as many issues and pull requests as you want. You should expect a timely and considered response.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmcc007%2Fsylph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmcc007%2Fsylph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmcc007%2Fsylph/lists"}