npm package: @open-xchange/codecept-plugin-filter
Description: A plugin for CodeceptJS that removes skipped tests from the test suite
Latest version: 0.1.0

# @open-xchange/codecept-plugin-filter

A plugin for [CodeceptJS](https://codecept.io/) that removes skipped tests from the test suite.

By default, CodeceptJS leaves skipped tests in the test suite, and will include them in the test results report.
This plugin removes skipped tests from the test suite entirely.
Additionally, the plugin will skip and remove more tests specified either in the plugin options or in specific environment variables.

The following tests will be removed from the test suite:

- Tests explicitly marked as skipped in source code (`Scenario.skip` and `Scenario.todo`).
- Tests with titles matching specific patterns passed into the plugin.
- Tests with titles matching specific patterns contained in environment variables:
  - Tests matching the pattern in `SKIP_TESTS` will always be skipped.
  - Tests matching the pattern in `SKIP_TESTS_CI` will be skipped when running in CI mode.
  - Tests matching the pattern in `SKIP_TESTS_LOCAL` will be skipped when _not_ running in CI mode.
  - The names of all environment variables can be customized via plugin options.

## Installation

```sh
npm install -D @open-xchange/codecept-plugin-filter
# or
pnpm add -D @open-xchange/codecept-plugin-filter
# or
yarn add -D @open-xchange/codecept-plugin-filter
```

## Usage

Add the plugin to the CodeceptJS `plugins` configuration (the object key `filter` can be changed):

```ts
// codecept.config.ts
export const config: CodeceptJS.MainConfig = {
  plugins: {
    filter: {
      require: '@open-xchange/codecept-plugin-filter',
      enabled: true,
      // plugin options:
      skipTests: ['@tag1', 'ISSUE-42'],
      skipTestsEnvVar: 'CUSTOM_VAR',
      skipTestsCIEnvVar: 'CUSTOM_VAR_CI',
      skipTestsLocalEnvVar: 'CUSTOM_VAR_LOCAL',
    },
  }
}
```

Add TypeScript type-safety for the plugin options by explicitly narrowing the configuration object using the `satisfies` keyword:

```ts
// codecept.config.ts
import type filterPlugin from '@open-xchange/codecept-plugin-filter'
export const config: CodeceptJS.MainConfig = {
  plugins: {
    filter: {
      require: '@open-xchange/codecept-plugin-filter',
      enabled: true,
      // ...
    } satisfies filterPlugin.Config,
  }
}
```

### Plugin Options

#### `skipTests`

- Type: `string | readonly string[] | RegExp`
- Default: `[]`

Additional tests to be skipped and removed from the test suite.
Can be one or more strings (literal substring matches) or a regular expression.
Test tags can be selected by using a leading `@` sign, e.g. `'@some-tag'`.

#### `skipTestsEnvVar`

- Type: `string | null`
- Default: `'SKIP_TESTS'`

The name of the environment variable containing a regular expression pattern for test titles to be skipped and removed from the test suite.
Test tags can be selected by using a leading `@` sign, e.g. `'@some-tag'`.

Can be set to `null` to skip parsing an environment variable.

#### `skipTestsCIEnvVar`

- Type: `string | null`
- Default: `'SKIP_TESTS_CI'`

The name of the environment variable containing a regular expression pattern for test titles to be skipped and removed from the test suite when running in CI mode only (when environment variable `CI` is set).
Test tags can be selected by using a leading `@` sign, e.g. `'@some-tag'`.

Matching tests will be filtered additionally to the tests selected with the environment variable from option `skipTestsEnvVar`.

Can be set to `null` to skip parsing an environment variable.

#### `skipTestsLocalEnvVar`

- Type: `string | null`
- Default: `'SKIP_TESTS_LOCAL'`

The name of the environment variable containing a regular expression pattern for test titles to be skipped and removed from the test suite when _not_ running in CI mode (when environment variable `CI` is not set).

Matching tests will be filtered additionally to the tests selected with the environment variable from option `skipTestsEnvVar`.

Can be set to `null` to skip parsing an environment variable.