Run TAP unit tests in 1789+ browsers. Airtap is a command-line interface to unit test your JavaScript in browsers, using a TAP-producing harness like tape. Start testing locally and seamlessly move to browsers in the cloud for full coverage. Airtap runs browsers concurrently and lets you iterate quickly during development. Don't just claim your JavaScript supports "all browsers", prove it with tests!
With npm do:
npm install airtap --save-dev
If you are upgrading or migrating from zuul: please see the upgrade guide.
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:
airtap test.js
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-system
browsers:
- 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-system
browsers:
- name: ff
version: 78
You can also match browsers by provider:
browsers:
- name: ff
provider: 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:
$ 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: chromium
options:
headless: false
launch:
args: [--lang=en-US]
For more information on the browsers field, see Configuration.
Providers must be installed separately.
| Package | Description |
|---|---|
airtap-system | Locally installed browsers on Linux, Mac & Windows |
airtap-playwright | Playwright (headless Chromium, FF and WebKit) |
airtap-sauce | Remote browsers in Sauce Labs |
airtap-electron | Electron |
airtap-default | Default browser |
airtap-manual | Manually open a URL in a browser of choice |
The airtap-sauce provider runs browsers on Sauce Labs. Sauce Labs offers quite a few browsers, with a wide range of versions and platforms.
Open source projects can use the free for open source version of Sauce Labs.
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 SAUCE_USERNAME and SAUCE_ACCESS_KEY.
Add the airtap-sauce provider and wanted browsers to .airtap.yml:
providers:
- airtap-sauce
browsers:
- name: chrome
- name: ios_saf
- name: ie
Airtap runs a server to serve JavaScript test files to browsers. The 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 hosts file:
127.0.0.1 airtap.local
You are now ready to run your tests in the cloud with airtap test.js.
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.
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_js
node_js:
- 12
addons:
hosts:
- airtap.local
Add the following to your package.json:
{
"scripts": {
"test": "airtap test.js"
}
}
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:
{
"scripts": {
"test": "airtap --coverage test.js"
}
}
You can choose to post the results to coveralls (or similar) by adding a step to .travis.yml:
after_success: npm run coverage
{
"scripts": {
"test": "airtap --coverage test.js",
"coverage": "nyc report --reporter=text-lcov | coveralls"
}
}
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: SAUCE_USERNAME and SAUCE_ACCESS_KEY.
Should work in theory :)
Usage: 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
List all available browsers:
airtap -la
Test browsers specified in .airtap.yml:
airtap test.js
Test all available browsers (careful):
airtap -a test.js
Test multiple files:
airtap "test/*.js"
Airtap consumes a YAML config file at .airtap.yml in the working directory. The following fields are available.
providers (array)browsers (array)List of browsers to test in the cloud. Each entry should contain a name property. Additional properties like version and platform may be specified depending on the provider.
The 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 beta or dev.
browsers:
- name: chrome
- name: firefox
version: beta
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: chrome
version: 28
platform: Windows XP
browsers:
- name: firefox
version: 14..latest
- name: ie
version: 9..11
This example would test the latest three stable versions of Firefox (latest - 2, latest - 1, latest).
browsers:
- name: firefox
version: -2..latest
browsers:
- name: firefox
version: [19, 20]
browsers:
- name: firefox
version: [19, 20, 23..latest]
- name: chrome
version: [-1..latest, beta]
browsers:
- name: ios_saf
version: '8.0..latest'
Float version numbers should be quoted.
browserify (array)You can set any of the items in the following list, and they'll be passed to browserify.
pluginexternalignoreexcludetransformaddrequireThey can be repeated and accept options.
browserify:
- require: ./some-file.js
expose: intimidate
- transform: brfs
- transform: jadeify
You can also customize what's passed to browserify(options).
browserify:
- options:
node: true
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 < 11
browserify:
- require: 'buffer/'
expose: 'buffer'
server (string or object)This field can point to an optional shell command or JavaScript file to run as a support server. It will be started before all tests and stopped afterwards. This allows testing websockets and other network requests. Your command will be run with the 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: ./test/support/server.js
We recommend writing simple support servers using http or express. For shell commands you can use $AIRTAP_SUPPORT_PORT in the arguments, which will be substituted:
server: "python -m SimpleHTTPServer $AIRTAP_SUPPORT_PORT"
The 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: firefox
options:
profile:
webgl.force-enabled: true
Lots of folks! Collectively, packages that depend on Airtap get 100's of millions of downloads per month!
level (and dependencies)webtorrent (and dependencies)simple-peerbufferstream-httpreadable-streamAirtap 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.
MIT © Roman Shtylman, Zuul contributors and Airtap contributors.
[4.0.0] - 2020-09-19
Airtap 4 is a modular rewrite that supports concurrent local browsers, headless testing with Playwright, starting Sauce Labs from your local machine & from GitHub Actions, and live reload on any browser. For details, please see the upgrade guide.
FAQs
Run TAP unit tests in 1789+ browsers
The npm package airtap receives a total of 1,652 weekly downloads. As such, airtap popularity was classified as popular.
We found that airtap demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.