1.3 Run single test or suite

Running a test file or folder can be helpful when pinpointing which tests are failing and why.

In order to debug it’s often necessary to do some sanity checks. For example, does the test fail if it’s run by itself? Does the test fail when another test is not run?

Tests failing only when some other test(s) are run alongside it, tends to be a sign of side-effectful mocking. In such a situation, finding the test which is not correctly implementing setup/teardown of mocks and stubs needs to be done rigorously.

Use .only to run only certain tests

Run a single Jest test in a file using .only

To run a single Jest test in a given file, use .only on the relevant test entry:

describe('my suite', () => {
  test.only('my only true test', () => {
    expect(1 + 1).toEqual(2);
  });
  // should fail, but isn't even run
  test('my only true test', () => {
    expect(1 + 1).toEqual(1);
  });
});

See the output, in which we ran 1 test (that had .only) and skipped/ignored one that would have failed.

npx jest src/01.03-single-only-test.test.js
 PASS  src/single-only-test.test.js
  my suite
    ✓ my only true test (6ms)
    ○ skipped my only true test

Test Suites: 1 passed, 1 total
Tests:       1 skipped, 1 passed, 2 total
Snapshots:   0 total
Time:        1.623s
Ran all test suites matching /src\/01.03-single-only-test.test.js/i.

Run multiple Jest tests in a file using .only

To run multiple (but not all) Jest tests in a file, you can use multiple test.only entries:

describe('my suite', () => {
  test.only('one of my .only test', () => {
    expect(1 + 1).toEqual(2);
  });
  test.only('other of my .only test', () => {
    expect(1 + 2).toEqual(3);
  });
  // Should fail, but isn't even run
  test('my only true test', () => {
    expect(1 + 1).toEqual(1);
  });
});

See the output, in which we ran 2 tests (that had .only) and skipped/ignored one that would have failed.

npx jest src/01.03-many-only-tests.test.js
 PASS  src/many-only-tests.test.js
  my suite
    ✓ one of my .only test (4ms)
    ✓ other of my .only test
    ○ skipped my only true test

Test Suites: 1 passed, 1 total
Tests:       1 skipped, 2 passed, 3 total
Snapshots:   0 total
Time:        2.483s
Ran all test suites matching /src\/01.03-many-only-tests.test.js/i.

.only to run a single suite of tests in a describe

A whole describe can have the .only, which means that section of the suite will be run but nothing else:

describe.only('my suite', () => {
  test.only('one of my .only test', () => {
    expect(1 + 1).toEqual(2);
  });
});
describe('my other suite', () => {
  // Should fail, but isn't even run
  test('my only true test', () => {
    expect(1 + 1).toEqual(1);
  });
});

See the output, in which we ran 1 suite (that had .only) and skipped/ignored one suite that would have had a failing test.

npx jest src/01.03-single-only-describe.test.js
 PASS  src/single-only-describe.test.js
  my suite
    ✓ one of my .only test (4ms)
  my other suite
    ○ skipped my only true test

Test Suites: 1 passed, 1 total
Tests:       1 skipped, 1 passed, 2 total
Snapshots:   0 total
Time:        1.709s
Ran all test suites matching /src\/01.03-single-only-describe.test.js/i.

.only to run multiple suites of tests in describe-s

Multiple describe-s can have .only, which means those suites will be run but nothing else:

describe.only('my suite', () => {
  test('one of my .only test', () => {
    expect(1 + 1).toEqual(2);
  });
});
describe.only('other suite', () => {
  test('other of my .only test', () => {
    expect(1 + 2).toEqual(3);
  });
});
describe('skipped other suite', () => {
  // Should fail, but isn't even run
  test('my only true test', () => {
    expect(1 + 1).toEqual(1);
  });
});

See the output, in which we ran 2 suites (that had .only) and skipped/ignored one suite that would have had a failing test.

npx jest src/01.03-many-only-describes.test.js
 PASS  src/many-only-describes.test.js
  my suite
    ✓ one of my .only test (4ms)
  other suite
    ✓ other of my .only test (1ms)
  skipped other suite
    ○ skipped my only true test

Test Suites: 1 passed, 1 total
Tests:       1 skipped, 2 passed, 3 total
Snapshots:   0 total
Time:        2.235s
Ran all test suites matching /src\/01.03-many-only-describes.test.js/i.

Use .skip to ignore Jest tests or suites

Ignore a single Jest test in a file using .skip

To skip a single Jest test in a given file, use .skip on the relevant test entry:

describe('my suite', () => {
  test('my only true test', () => {
    expect(1 + 1).toEqual(2);
  });
  // Should fail, but isn't even run
  test.skip('my only true test', () => {
    expect(1 + 1).toEqual(1);
  });
});

See the output, in which we ran 1 test (that didn’t have .skip) and skipped/ignored one that would have failed (that had .skip).

npx jest src/01.03-single-skip-test.test.js
 PASS  src/single-skip-test.test.js
  my suite
    ✓ my only true test (4ms)
    ○ skipped my only true test

Test Suites: 1 passed, 1 total
Tests:       1 skipped, 1 passed, 2 total
Snapshots:   0 total
Time:        1.737s
Ran all test suites matching /src\/01.03-single-skip-test.test.js/i.

Skip multiple Jest tests in a file using .skip

To skip multiple (but not all) Jest tests in a file, you can use multiple test.skip entries:

describe('my suite', () => {
  test('one of my tests', () => {
    expect(1 + 1).toEqual(2);
  });
  test.skip('skipped failing test', () => {
    expect(1 + 2).toEqual(3);
  });
  test.skip('my only true test', () => {
    expect(1 + 1).toEqual(1);
  });
});

See the output, in which we ran 1 test (that didn’t have .skip) and skipped/ignored the two that would have failed (and had .skip).

npx jest src/01.03-many-skip-tests.test.js
 PASS  src/many-skip-tests.test.js
  my suite
    ✓ one of my tests (4ms)
    ○ skipped skipped failing test
    ○ skipped my only true test

Test Suites: 1 passed, 1 total
Tests:       2 skipped, 1 passed, 3 total
Snapshots:   0 total
Time:        1.484s
Ran all test suites matching /src\/01.03-many-skip-tests.test.js/i.

Ignore a single suite of tests in a describe with .skip

To skip a single Jest describe in a given file, use .skip on the relevant describe entry:

describe('my suite', () => {
  test('one of my tests', () => {
    expect(1 + 1).toEqual(2);
  });
});

describe.skip('my other suite', () => {
  test('my only true test', () => {
    expect(1 + 1).toEqual(1);
  });
});

See the output, in which we ran 1 test (that didn’t have .skip) and skipped/ignored one that would have failed (whose describe block had .skip).

npx jest src/01.03-single-skip-describe.test.js
 PASS  src/single-skip-describe.test.js
  my suite
    ✓ one of my tests (5ms)
  my other suite
    ○ skipped my only true test

Test Suites: 1 passed, 1 total
Tests:       1 skipped, 1 passed, 2 total
Snapshots:   0 total
Time:        1.63s, estimated 2s
Ran all test suites matching /src\/01.03-single-skip-describe.test.js/i.

Ignore multiple suites of tests in describe-s with .skip

To skip multiple (but not all) Jest describe-s in a file, you can use multiple describe.skip entries:

describe('my suite', () => {
  test('one of my test', () => {
    expect(1 + 1).toEqual(2);
  });
});
describe.skip('other suite', () => {
  // Should fail, but isn't even run
  test('other of my .skip test', () => {
    expect(1 + 2).toEqual(4);
  });
});
describe.skip('skipped other suite', () => {
  // Should fail, but isn't even run
  test('my only true test', () => {
    expect(1 + 1).toEqual(1);
  });
});

See the output, in which we ran 1 test (that didn’t have .skip) and skipped/ignored the two that would have failed (whose describe had .skip).

npx jest src/01.03-many-skip-describes.test.js
 PASS  src/many-skip-describes.test.js
  my suite
    ✓ one of my test (4ms)
  other suite
    ○ skipped other of my .skip test
  skipped other suite
    ○ skipped my only true test

Test Suites: 1 passed, 1 total
Tests:       2 skipped, 1 passed, 3 total
Snapshots:   0 total
Time:        3.071s
Ran all test suites matching /src\/01.03-many-skip-describes.test.js/i.

This section showed how we can use the .only and .skip modifiers on describe and test blocks in order to run a subset of tests within a file.

The downside of this approach is that it changes the test code itself. In order to achieve the same kind of behaviour it’s possible to use the interactive watch mode filters, as we will see in the next section.

Jump to table of contents