JavaScript collectors

Add the test collector package

Whichever test framework you use, you first need to add and authenticate the buildkite-test-collector.

To add the test collector package:

1. In your CI environment, set the BUILDKITE_ANALYTICS_TOKEN environment variable to your Test Engine API token. To learn how to set environment variables securely in Pipelines, see Managing pipeline secrets.

2. On the command line, create a new branch by running:

   git checkout -b install-buildkite-test-engine
   

3. Install buildkite-test-collector using your package manager.

   For npm, run:

   npm install --save-dev buildkite-test-collector
   

   For yarn, run:

   yarn add --dev buildkite-test-collector
   

Configure the test framework

With the test collector installed, you need to configure it in the test framework.

Jest

If you're already using Jest, you can add buildkite-test-collector/jest/reporter to the list of reporters to collect test results into your Test Engine dashboard.

To configure Jest:

1. Make sure Jest runs with access to CI environment variables.

2. Add "buildkite-test-collector/jest/reporter" to Jest's reporters configuration array (typically found in jest.config.js, jest.config.js, or package.json):

   {
       "reporters": ["default", "buildkite-test-collector/jest/reporter"],
       "testLocationInResults": true,
   }
   

   Note: The "testLocationInResults": true setting enables column and line capture for Test Engine.

Jasmine

To configure Jasmine:

1. Follow the Jasmine docs to add the Buildkite reporter. For example:

   // SpecHelper.js
   var BuildkiteReporter = require("buildkite-test-collector/jasmine/reporter");
   var buildkiteReporter = new BuildkiteReporter();
   
   jasmine.getEnv().addReporter(buildkiteReporter);
   

2. (Optional) To pass in the API token using a custom environment variable, use the following report options:

   // SpecHelper.js
   var buildkiteReporter = new BuildkiteReporter(undefined, {
       token: process.env.CUSTOM_ENV_VAR,
   });
   

Mocha

To configure Mocha:

1. Install the mocha-multi-reporters in your project by running:

   npm install mocha-multi-reporters --save-dev
   

2. Configure it to run your desired reporter and the Buildkite reporter:

   // config.json
   {
     "reporterEnabled": "spec, buildkite-test-collector/mocha/reporter"
   }
   

3. Update your test script to use the Buildkite reporter via mocha-multi-reporters:

   // package.json
   "scripts": {
     "test": "mocha --reporter mocha-multi-reporters --reporter-options configFile=config.json"
   },
   

4. (Optional) To pass in the API token using a custom environment variable, use the report options. Since the reporter options are passed in as a JSON file, we recommend you put the environment variable name as a string value in the config.json, which is retrieved using dotenv in the mocha reporter.

   // config.json
   {
     "reporterEnabled": "spec, buildkite-test-collector/mocha/reporter",
     "buildkiteTestCollectorMochaReporterReporterOptions": {
       "token_name": "CUSTOM_ENV_VAR_NAME"
     }
   }
   

Cypress

To configure Cypress:

1. Make sure Cypress runs with access to CI environment variables.

2. Update your Cypress configuration.

   // cypress.config.js
   
   // Send results to Test Engine
   reporter: "buildkite-test-collector/cypress/reporter",
   

   Note: To pass in the API token using a custom environment variable, add the reporterOptions option to your Cypress configuration:

   // cypress.config.js
   
   // Send results to Test Engine
   reporterOptions: {
     token_name: "CUSTOM_ENV_VAR_NAME"
   }
   

Playwright

If you're already using Playwright, you can add buildkite-test-collector/playwright/reporter to the list of reporters to collect test results into your Test Engine dashboard.

To configure Playwright:

1. Make sure Playwright runs with access to CI environment variables.

2. Add "buildkite-test-collector/playwright/reporter" to Playwright's reporter configuration array (typically found in playwright.config.js):

   // playwright.config.js
   {
     "reporter": [
       ["line"],
       ["buildkite-test-collector/playwright/reporter"]
     ]
   }
   

Save the changes

When your collector is installed, commit and push your changes:

1. Add the changes to the staging area by running:

   git add .
   

2. Commit the changes by running:

   git commit -m "Install and set up Buildkite Test Engine"
   

3. Push the changes by running:

   git push
   

View the results

After completing these steps, you'll see the analytics of test executions on all branches that include this code in the Test Engine dashboard.

If you don't see branch names, build numbers, or commit hashes in the Test Engine dashboard, see CI environments to learn more about exporting your environment.

Troubleshooting missing test executions and --forceExit

Using the --forceExit option when running Jest could result in missing test executions from Test Engine.

--forceExit could potentially terminate any ongoing processes that are attempting to send test executions to Buildkite.

We recommend using --detectOpenHandles to track down open handles which are preventing Jest from exiting cleanly.