Metadata and Filtering

Metadata and filters are powerful tools that help TestCafe users manage their test suites and test runs.

  • Use metadata to embed custom information into your test suite.
  • Use filters to only run tests or fixtures that satisfy specific criteria.

Metadata

Users can embed custom metadata into fixture and test definitions. You can use this data to:

Define Fixture Metadata

The fixture.meta method defines fixture metadata.

Pass two strings to the meta method to define a single key-value pair. Pass a JSON array to define multiple key-value pairs:

fixture `My fixture`
    .meta('fixtureID', 'f-0001')
    .meta({ author: 'John', creationDate: '05/03/2018' });

Define Test Metadata

The test.meta method defines test metadata.

Pass two strings to the meta method to define a single key-value pair. Pass a JSON array to define multiple key-value pairs:

test
    .meta('testID', 't-0005')
    .meta({ severity: 'critical', testedAPIVersion: '1.0' })
    ('MyTest', async t => { /* ... */});

Include Metadata in Run Reports

Regular TestCafe installations do not include reporters that output test metadata. If you want to include specific metadata in your reports, create a custom reporter. Custom reporters can access metadata with the reportFixtureStart and reportTestDone methods.

Filter Tests and Fixtures

Use filters to only run tests or fixtures that satisfy specific criteria. You can filter tests and fixtures by metadata or file name. You can also filter tests and fixtures by test name: either with a strict match or a regular expression.

Additionally, you can skip certain tests and fixtures, or mark them for execution.

Filter by Name (Strict Match)

CLI

The -t (--test) command line option filters tests by name:

testcafe safari ./tests/sample-fixture.js -t "Click a label"

The -f (--fixture) command line option filters fixtures by name:

testcafe firefox ./my-tests/ -f "Sample fixture"

Runner

The runner.filter Test Runner method executes filter functions.

Pass the testName and/or the fixtureName argument to the filter function. Then create a condition that compares the argument’s actual value to the desired value.

await runner
    .browsers('safari')
    .src('./tests/sample-fixture.js')
    .filter(testName => testName === 'Click a label')
    .run();

await runner
    .browsers('firefox')
    .src('./my-tests/')
    .filter((testName, fixtureName) => fixtureName === 'Sample fixture')
    .run();

Configuration file

The filter.test configuration file property filters tests by name.

The filter.fixture configuration file property filters fixtures by name.

Filter by Name (RegExp)

If a strict match doesn’t satisfy your needs, you can filter fixtures and tests by regular expression.

CLI

The -T (--test-grep) command line option filters tests by regular expression:

testcafe chrome ./my-tests/ -T "Click.*"

The -F (--fixture-grep) command line option filters fixtures by regular expression:

testcafe safari ./my-tests/ -F "Page.*"

Runner

The runner.filter Test Runner method executes filter functions.

Pass the testName and/or the fixtureName argument to the filter function. Then create a condition that compares the argument’s actual value to the regular expression.

Configuration File

The filter.testGrep configuration file property filters tests by regular expression.

The filter.fixtureGrep configuration file property filters fixtures by regular expression.

Filter by Metadata

CLI

The --test-meta command line option filters tests by metadata:

testcafe chrome ./my-tests/ --test-meta device=mobile,env=production

The --fixture-meta command line option filters fixtures by metadata:

testcafe firefox ./my-tests/ --fixture-meta device=mobile,env=production

Runner

The runner.filter Test Runner method executes filter functions.

To filter tests, pass the testMeta parameter to the filter function. Then create a condition that compares the actual value of testMeta parameters to the value you expect.

await runner
    .browsers('chrome')
    .src('./my-tests/')
    .filter((testName, fixtureName, fixturePath, testMeta) => {
        return testMeta.device === 'mobile' && testMeta.env === 'production';
    })
    .run();

To filter fixtures, pass the fixtureMeta parameter to the filter function. Then create a condition that compares the actual value of fixtureMeta parameters to the value you expect.

await runner
    .browsers('firefox')
    .src('./my-tests/')
    .filter((testName, fixtureName, fixturePath, testMeta, fixtureMeta) => {
        return fixtureMeta.device === 'mobile' && fixtureMeta.env === 'production';
    })
    .run();

Configuration file

You can filter tests by metadata with the filter.testMeta configuration file property. The filter.fixtureMeta property filters fixtures by metadata.

Filter by Glob Pattern

You can filter test files by glob pattern.

CLI

testcafe firefox ./tests/*mobile*

Runner

await runner
    .browsers('firefox')
    .src('./tests/*mobile*')
    .run();

Skip Tests and Fixtures

Use fixture.skip and test.skip methods to skip tests and fixtures one by one. 

fixture.skip `Fixture 1`; // Skip this fixture

test('Fixture 1 - Test 1', () => {});
test('Fixture 1 - Test 2', () => {});

fixture `Fixture 2`;

test('Fixture 2 - Test 1', () => {});
test.skip('Fixture 2 - Test 2', () => {}); // Skip this test
test('Fixture 2 - Test 3', () => {});

Mark Tests and Fixtures for Execution

Use fixture.only and test.only methods to mark fixtures and tests for execution. You can use the only method to mark multiple tests and/or fixtures.

fixture.only `Fixture 1`; // Execute this fixture
test('Fixture 1 - Test 1', () => {});
test('Fixture 1 - Test 2', () => {});

fixture `Fixture 2`;

test('Fixture 2 - Test 1', () => {});
test.only('Fixture 2 - Test 2', () => {}); // Out of all the tests in this fixture, only execute this one
test('Fixture 2 - Test 3', () => {});

fixture `Fixture 3`; // TestCafe does not execute this fixture since it lacks the 'only' flag

test('Fixture 3 - Test 1', () => {});
test('Fixture 3 - Test 2', () => {});
test('Fixture 3 - Test 3', () => {});