airtap

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!


Install

With npm do:

``
npm install airtap --save-dev
`

If you are upgrading or migrating from zuul: please see the upgrade guide.

Getting Started

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
`

$3

In order to run more browsers, create a .airtap.yml file in your working directory, containing at least one provider and browser. For example:

`yaml
providers:
- airtap-system

browsers:
- name: chrome
- name: ff
`

Providers discover browsers on a particular platform or remote service. In the above example, [airtap-system][airtap-system] finds browsers installed on your machine which Airtap then matches against the specified browsers. Providers are npm packages that must be installed separately from the main airtap package. So that would be:

`
npm install airtap airtap-system --save-dev
`

You can include multiple providers and let Airtap find the best matching browser(s):

`yaml
providers:
- airtap-playwright
- airtap-system

browsers:
- name: ff
version: 78
`

You can also match browsers by provider:

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 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:

`yaml
browsers:
- name: chromium
options:
headless: false
launch:
args: [--lang=en-US]
`

For more information on the browsers field, see Configuration.

Available Providers

| Package | Description |
| :--------------------------------------- | :------------------------------------------------- |
| [airtap-system][airtap-system] | Locally installed browsers on Linux, Mac & Windows |
| [airtap-playwright][airtap-playwright] | Playwright (headless Chromium, FF and WebKit) |
| [airtap-sauce][airtap-sauce] | Remote browsers in Sauce Labs |
| [airtap-electron][airtap-electron] | Electron |
| [airtap-default][airtap-default] | Default browser |
| [airtap-manual][airtap-manual] | Manually open a URL in a browser of choice |

Cloud Testing With Sauce Labs

The [airtap-sauce][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._

$3

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.

$3

Add the airtap-sauce provider and wanted browsers to .airtap.yml:

`yaml
providers:
- airtap-sauce

browsers:
- name: chrome
- name: ios_saf
- name: ie
`

$3

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.

Continuous Integration

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.

![Sauce Test Status](https://saucelabs.com/u/level-js)

$3

#### 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:

`yaml
language: node_js
node_js:
- 12
addons:
hosts:
- airtap.local
`

#### 2. Add Test Script

Add the following to your package.json:

`json
{
"scripts": {
"test": "airtap test.js"
}
}
`

#### 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:

`json
{
"scripts": {
"test": "airtap --coverage test.js"
}
}
`

You can choose to post the results to coveralls (or similar) by adding a step to .travis.yml:

`yaml
after_success: npm run coverage
`

`json
{
"scripts": {
"test": "airtap --coverage test.js",
"coverage": "nyc report --reporter=text-lcov | coveralls"
}
}
`

#### 4. Set Credentials

Skip this step if you're not using the [airtap-sauce][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.

$3

Should work in theory :)

CLI

Usage: airtap [options] . 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 and exit
-l --list-browsers List (effective or --all) browsers
-a --all Test or list all available browsers
--coverage Enable code coverage analysis
--live Keep browsers open to allow repeated test runs
-c --concurrency Number of browsers to test concurrently, default 5
-r --retries Number of retries when running a browser, default 6
-t --timeout How long to wait for test results, default 5m. Can
be a number in milliseconds or a string with unit.
-p --preset Select a configuration preset
-s --server