npm package: @saucelabs/playwright-reporter
Description: Reports your tests to Sauce Labs
Author: devx
Latest version: 1.6.0

# sauce-playwright-plugin

This Playwright plugin reports each project to your Sauce Labs account.

## Installation

Install from npm:

```sh
npm install @saucelabs/playwright-reporter
```

### Sauce Labs Credentials

Set the `SAUCE_USERNAME` and `SAUCE_ACCESS_KEY` environment variables to allow the plugin to report your results to Sauce Labs. Your Sauce Labs Username and Access Key are available from your [dashboard](https://app.saucelabs.com/user-settings).

## Usage

Add to the default reporter:

```sh
npx playwright test --reporter=line,@saucelabs/playwright-reporter
```

Use only `@saucelabs/playwright-reporter`:

```sh
npx playwright test --reporter=@saucelabs/playwright-reporter
```

You can also configure it using `playwright.config.js`. To do that, add `'@saucelabs/playwright-reporter'` to the reporter section of your configuration:

```js
const config = {
  reporter: [['@saucelabs/playwright-reporter']],
  // Rest of your config goes here
};
```

### Plugin Configuration

`@saucelabs/playwright-reporter` is configurable through your `playwright.config.js` or `playwright.config.ts` file.

Example:

```js
const config = {
  reporter: [
    [
      '@saucelabs/playwright-reporter',
      {
        buildName: 'My Playwright Build',
        region: 'us-west-1',
        tags: ['playwright', 'demo'],
      },
    ],
  ],
  // Rest of your config goes here
};
```

| Name          | Description                                                                                                                                                                                                                                                                                         | Type                          |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `buildName`   | Sets a build ID. <br> Default: `''`                                                                                                                                                                                                                                                                 | `string`                      |
| `tags`        | Tags to add to the uploaded Sauce job. <br> Default: `[]`                                                                                                                                                                                                                                           | `string[]`                    |
| `region`      | Sets the region. <br> Default: `us-west-1`                                                                                                                                                                                                                                                          | `us-west-1` \| `eu-central-1` |
| `upload`      | Whether to upload report and assets to Sauce Labs. <br> Default: `true`                                                                                                                                                                                                                             | `boolean`                     |
| `outputFile`  | The local path to write the Sauce test report. Can be set in env var `SAUCE_REPORT_OUTPUT_NAME`.                                                                                                                                                                                                    | `string`                      |
| `mergeVideos` | Whether to merge all video files generated by Playwright. This is useful when used with the `upload` option to upload the test report to Sauce Labs since it will allow you to view the merged video in the Sauce Labs Test Results page. **Requires ffmpeg to be installed.**<br> Default: `false` | `boolean`                     |

## Limitations

Some limitations apply to `@saucelabs/playwright-reporter`:

- For Playwright versions before v1.16.3, the Playwright version is not reported to Sauce Labs.
- The browser version is not reported to Sauce Labs.

## Development

### Setup

1. Install dependencies: `npm ci`
2. Setup git hooks: `npm run prepare`. This setups pre-commit hooks to format
   and lint staged code.
3. Build: `npm run build`

### Running Locally

There are tests included in `tests/integration` where the reporter is referenced
directly.

```sh
$ npm run build
$ cd tests/integration
$ npx playwright test
```

If you have playwright tests outside of the repo, you can use
[npm link](https://docs.npmjs.com/cli/v11/commands/npm-link) to install the
reporter to run in your external repo.

```sh
$ npm link @saucelabs/playwright-reporter
$ npx playwright test --reporter=@saucelabs/playwright-reporter
```

### Debug

You can run your Playwright tests with the environment variable
`DEBUG="@saucelabs/playwright-reporter:*"` to see additional debug output.

```sh
$ DEBUG="@saucelabs/playwright-reporter:*" npx playwright test --reporter=@saucelabs/playwright-reporter
```

## Releasing

New versions are released with a manual GitHub Actions workflow.

1. Go to https://github.com/saucelabs/sauce-cypress-plugin/actions/workflows/release.yml
2. Run the workflow and specify the branch and release type (`major`, `minor`,
   or `patch`).