A sylph is a mythological invisible being of the air. Wikipedia
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.
Sylph works with AWS Device Farm for up to hundreds of Android and iOS devices in a single run.
pub global activate sylph
or, if not using the default config file:
sylph -c <path to config file>
usage: sylph [--help] [--config <config file>] [--devices <all|android|ios>] [--verbose] sample usage: sylph -c, --config=<sylph.yaml> Path to config file. (defaults to "sylph.yaml") -d, --devices=<all|android|ios> List devices available in cloud. [all, android, ios] -v, --verbose Noisy logging, including all shell commands executed. -h, --help Display this help information.
AWS CLI #
Install AWS Command Line Interface (AWS CLI)
curl "https://s3.amazonaws.com/aws-cli/awscli-bundle.zip" -o "awscli-bundle.zip" unzip awscli-bundle.zip sudo ./awscli-bundle/install -i /usr/local/aws -b /usr/local/bin/aws
pip install awscli
For alternative install options see:
AWS CLI Credentials #
Configure the AWS CLI credentials:
$ aws configure AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Default region name [None]: us-west-2 Default output format [None]: json
For alternative configuration options see:
Test AWS CLI #
Confirm AWS CLI is installed and configured correctly by running an AWS command. For example, the following command should generate output:
aws devicefarm list-projects
Configuration information is passed to Sylph using a configuration file. The default config file is called
# Config file for Flutter tests on real device pools. # Auto-creates projects and device pools if needed. # Configures android and ios test runs. # Builds app, uploads and runs tests. # Then monitors tests, returns final pass/fail result and downloads artifacts. # Note: assumes the 'aws' command line utility is logged-in. # Note: to build the debug iOS app, certain environment variables are required. # sylph config tmp_dir: /tmp/sylph artifacts_dir: /tmp/sylph_artifacts # local timeout per device farm run sylph_timeout: 720 # seconds approx # run on ios and android pools concurrently (for faster results) concurrent_runs: true # device farm config project_name: App Integration Tests default_job_timeout: 10 # minutes, set at project creation device_pools: - pool_name: android pool 1 pool_type: android devices: - name: Google Pixel 2 model: Google Pixel 2 os: 8.0.0 - pool_name: ios pool 1 pool_type: ios devices: - name: Apple iPhone X model: A1865 os: 11.4 test_suites: - test_suite: example tests 1 main: test_driver/main.dart tests: - test_driver/main_test.dart pool_names: - android pool 1 - ios pool 1 job_timeout: 15 # minutes, set per job, over-rides default job timeout above
Multiple test suites, consisting of multiple tests, can be run on each device in each device pool. The 'main' app must include a call to
Device pools can consist of multiple devices. Devices in a device pool must be of the same type, iOS or Android.
Note: 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.
Building an iOS debug app #
To build a testable iOS app locally, that can run on any real device in the cloud, the following environment variable must be present:
This is the Developer Portal Team ID. It is of the form 'ABCDEFGHIJ'.
A check is made before the start of a run to confirm this environment variable is present.
Note: if not running on an iOS pool this environment variable is not required.
Populating a device pool #
To add devices to a device pool, pick devices from the list provided by
sylph -d android or sylph -d ios
and add to the appropriate pool type in sylph.yaml. The listed devices are devices currently available on Device Farm.
Configuration Validation #
The sylph.yaml is validated to confirm the devices are available on Device Farm and tests are present before starting a run.
If running on an iOS pool, the iOS-related environment variables must be defined.
Configuring Flavors #
A reference flavor app can be found in 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.
To enable testing on a flavor add the following to your sylph.yaml:
flavor: <name of flavor>
Configuring a CI Environment for Sylph
In addition to running from the command line, Sylph also runs in a CI environment.
AWS CLI Credentials for CI #
The following AWS CLI credentials are required in a CI environment:
For details on other credentials see:
iOS builds #
To 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.
The following environment variables are required by a CI build to use Fastlane match:
This is the location of the private match repo. It expects an ssh-based url. For example, ssh://email@example.com/private_repos/match.git
This is the password that was used to encrypt the git repo's contents during match setup.
For details on how to setup Match see:
The 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:
This is used to configure the CI's ssh client to find the match host. For example, private.mycompany.com.
This is used to configure the CI's ssh client to find the match host's ssh port. For example, 22.
As with running from the command line, the following environment variable is also required by Sylph in a CI environment:
This is the Developer Portal Team ID. It is of the form 'ABCDEFGHIJ'.
Note: if not running on an iOS pool all iOS-related environment variables are not required.
Sample environment variables for Travis-CI #
For example, when Sylph is run on Travis-CI the following environment variables are used:
See .travis.yml for running Sylph on Travis-CI.
Note: the Travis-CI build uses pre-configured AWS CLI values in .aws/config.
To upgrade, simply re-issue the install command
$ pub global activate sylph
To check the version of Sylph currently installed:
pub global list
Live demo #
To see Sylph in action in a CI environment, a demo of the example app is available.
The log of the live run on mac and linux is here:
The resulting artifacts are here:
(includes a video of test running on device)
To view a similar run on windows:
When contributing to this repository, please feel free to discuss via issue or pull request.
Your 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.
- Upgraded flutter to latest (1.12.13+hotfix.5) #82
(only used for running
- Fixed problem with .packages in latest flutter #87
- Fixed analyzer warnings and added example readme after publishing
- Fixed pub.dev warnings after publishing
- Fixed bug in gathering job args for concurrent runs #72
- Added support for flavors using 'recommended' example #75 #76
- Added support for bundling external local packages #73 #77
- Added verbose mode #56 #66
- Added support for linux and windows #50 #69
- Added support for bundling local packages #59
- Added code coverage #53
- Added form factor (phone/tablet) to device listing feature. Sorting by phone then table. #52 #53
- Added tracking error code when running on device farm. #45
- Removed dependency on env vars when not building for iOS. #41
- Fixed multiple tests not running on android devices. #31
- Added feature to support configuring a device pool. #35
Enables looking-up devices from the command line.
- Refactoring. #37
- Added support for configurable iOS build. #30
Requires adding environment variables.
- Removed dependency on forked flutter #13
- Added support for running sylph jobs in parallel #14
- Added support for downloading artifacts per device #15
- Added per job timeouts #17
- Added reporting of test progress per device in pool #19
- Added config validator at start of run #24 #25
- Resolved potential security vulnerability in fastlane #27
- Hid test_spec.yaml from user and allowed multiple tests to run on each device #20 #28
- Added support for iOS real devices
(now supports both iOS and Android real devices)
- Downloads artifacts from AWS Device Farm
(including video and log of running test)
- Initial version
A default app is in default_app.
A 'recommended' flavors app is in flavors.
Use this package as an executable
1. Install it
You can install the package from the command line:
$ pub global activate sylph
2. Use it
The package has the following executables:
Use this package as a library
1. Depend on it
Add this to your package's pubspec.yaml file:
dependencies: sylph: ^0.7.1
2. Install it
You can install packages from the command line:
$ pub get
$ flutter pub get
Alternatively, your editor might support
pub get or
flutter pub get.
Check the docs for your editor to learn more.
3. Import it
Now in your Dart code, you can use:
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
We analyzed this package on Feb 12, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:
- Dart: 2.7.1
- pana: 0.13.5
|Dart SDK||>=2.2.2 <3.0.0|