Table of Contents
Click to expand
- Getting Started
- Available Providers
- Cloud Testing With Sauce Labs
- Continuous Integration
server(string or object)
- Firefox Profile
- Who Uses Airtap?
With npm do:
npm install airtap --save-dev
You'll need an entry point for your tests like
test.js. For a complete example see
airtap-demo. If you already have an entry point, go ahead and run it with:
Out of the box, this will launch the default browser on your system. To keep the browser open and automatically reload when you make changes to your test files, run:
airtap --live test.js
In order to run other (and more than one) browsers, create a
.airtap.yml file in your working directory, containing at least one provider and at least one browser. For example:
providers:- airtap-systembrowsers:- name: chrome- name: ff
Providers discover browsers on a particular platform or remote service. In the above example,
airtap-system finds browsers installed on your machine which Airtap then matches against the
browsers you specified.
You can include multiple providers and let Airtap find the best matching browser(s):
providers:- airtap-playwright- airtap-systembrowsers:- name: ffversion: 78
You can also match browsers by provider:
Click to expand
browsers:- name: ffprovider: airtap-system
Airtap, providers and browsers are tied together by manifests. They define the name and other metadata of browsers. You can see these manifests by running
airtap -l or
-la which is short for
--list-browsers --all. For example:
Click to expand
$ airtap -la - name: electron title: Electron 9.0.5 version: 9.0.5 options: headless: true provider: airtap-electron
Airtap can match browsers on any manifest property, with the exception of
options which exists to customize the browser behavior. Options are specific to a provider. For example, the
airtap-playwright provider supports disabling headless mode and setting custom command-line arguments:
browsers:- name: chromiumoptions:headless: falselaunch:args: [--lang=en-US]
For more information on the
browsers field, see Configuration.
Providers must be installed separately.
||Locally installed browsers on Linux, Mac & Windows|
||Playwright (headless Chromium, FF and WebKit)|
||Remote browsers in Sauce Labs|
||Manually open a URL in a browser of choice|
Cloud Testing With Sauce Labs
Open source projects can use the free for open source version of Sauce Labs.
1. Set Credentials
Airtap needs to know your Sauce Labs credentials. You don't want to commit these sensitive credentials to your git repository. Instead set them via the environment as
2. Select Browsers
airtap-sauce provider and wanted browsers to
providers:- airtap-saucebrowsers:- name: chrome- name: ios_saf- name: ie
3. Set Hostname
airtap-sauce provider establishes a tunnel to your local machine so that Sauce Labs can find that server. For this to work, some browsers need a custom loopback hostname, because they don't route
localhost through the tunnel. Add the following to your
You are now ready to run your tests in the cloud with
After making sure your tests pass when initiated from your local machine, you can setup continuous integration to run your tests whenever changes are committed. Any CI service that supports Node.js will work.
1. Setup Travis
Take a look at the Travis getting started guide for Node.js. At minimum we need to create a
.travis.yml file containing:
language: node_jsnode_js:- 12addons:hosts:- airtap.local
2. Add Test Script
Add the following to your
3. Enable Code Coverage
Optionally enable code coverage with the
--coverage flag. This will collect code coverage per browser into the
.nyc-output/ folder in Istanbul 1.0 format. Afterwards you can generate reports with
nyc report, which takes care of merging code coverage from multiple browsers.
A typical setup for Travis looks like:
You can choose to post the results to
coveralls (or similar) by adding a step to
after_success: npm run coverage
4. Set Credentials
Skip this step if you're not using the
airtap-sauce provider. Same as when initiating tests locally, we need to get Sauce Labs credentials to Travis. Luckily Travis has a feature called secure environment variables. You'll need to set 2 of those:
Should work in theory :)
airtap [options] <files>. Supports multiple
files. They can be paths relative to the working directory or glob patterns (e.g.
airtap test/*.js). Options:
-v, --version print version -l, --list-browsers list (effective or --all) browsers -a, --all test or list all available browsers -c, --concurrency <n> number of browsers to test concurrently, default 5 -r, --retries <retries> number of retries when running a browser, default 6 -t, --timeout <timeout> how long to wait for test results, default 5m --coverage enable code coverage analysis --live keep browsers open to allow repeated test runs -p, --preset <preset> select a configuration preset -s, --server <script> path to script that runs a support server --loopback <hostname> custom hostname that equals or resolves to 127.0.0.1 --verbose enable airtap debug output --silly enable all debug output -h, --help display help for command
Examples (click to expand)
List all available browsers:
Test browsers specified in .airtap.yml:
Test all available browsers (careful):
airtap -a test.js
Test multiple files:
Airtap consumes a YAML config file at
.airtap.yml in the working directory. The following fields are available.
List of browsers to test in the cloud. Each entry should contain a
name property. Additional properties like
platform may be specified depending on the provider.
version property defaults to
latest and can be a specific version number, the keyword
latest, the keyword
oldest, or (for Firefox and Chrome) one of the keywords
browsers:- name: chrome- name: firefoxversion: beta
Specific version of a browser on a specific platform
Only supported by the
airtap-sauce provider at the time of writing, as other providers do not run browsers on a particular platform.
browsers:- name: chromeversion: 28platform: Windows XP
Range of versions of a browser
browsers:- name: firefoxversion: 14..latest- name: ieversion: 9..11
Range of versions with negative start index.
This example would test the latest three stable versions of Firefox (latest - 2, latest - 1, latest).
browsers:- name: firefoxversion: -2..latest
browsers:- name: firefoxversion: [19, 20]
Disjoint with ranges
browsers:- name: firefoxversion: [19, 20, 23..latest]- name: chromeversion: [-1..latest, beta]
Float version numbers
browsers:- name: ios_safversion: '8.0..latest'
Float version numbers should be quoted.
You can set any of the items in the following list, and they'll be passed to
They can be repeated and accept options.
browserify:- require: ./some-file.jsexpose: intimidate- transform: brfs- transform: jadeify
You can also customize what's passed to
browserify:- options:node: true
IE < 11 support
To support IE < 11, an older version of the
buffer polyfill is required. Use the following configuration and run
npm install buffer@4:
# Use buffer@4 to support IE < 11browserify:- require: 'buffer/'expose: 'buffer'
server (string or object)
AIRTAP_SUPPORT_PORT environment variable set to a port number you must use. If your server does not listen on this port it will be unreachable (on browser providers that use a tunnel).
server: "python -m SimpleHTTPServer $AIRTAP_SUPPORT_PORT"
airtap-sauce provider supports running Firefox instances with custom user profiles. This allows you to configure anything you can change in
about:config programmatically for a test run. You can set these options with a section under any Firefox browser entry:
browsers:- name: firefoxoptions:profile:webgl.force-enabled: true
Who Uses Airtap?
Lots of folks! Collectively, packages that depend on Airtap get 100's of millions of downloads per month!
- Send a PR to add your package to the list!
Airtap is an OPEN Open Source Project. This means that:
Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.
See the contribution guide for more details.