Глобальные объекты

В файлах тестов Jest помещает каждый из этих методов и объектов в глобальное окружение. Чтобы использовать их, ничего не нужно подключать с помощью require или import. Однако, если вы предпочитаете явный импорт, можно сделать import {describe, expect, test} from '@jest/globals'.

import {expect, jest, test} from '@jest/globals';

Методы

Справочник

afterAll(fn, timeout)

Запускает функцию после завершения всех тестов в этом файле. Если функция возвращает промис или является генератором, Jest дожидается разрешения этого промиса, прежде чем продолжить.

При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Это часто полезно, если нужно очистить некоторое состояние глобальной настройки, общее для нескольких тестов.

Например:

const globalDatabase = makeGlobalDatabase();

function cleanUpDatabase(db) {
  db.cleanUp();
}

afterAll(() => {
  cleanUpDatabase(globalDatabase);
});

test('can find things', () => {
  return globalDatabase.find('thing', {}, results => {
    expect(results.length).toBeGreaterThan(0);
  });
});

test('can insert a thing', () => {
  return globalDatabase.insert('thing', makeThing(), response => {
    expect(response.success).toBeTruthy();
  });
});

Здесь afterAll гарантирует, что cleanUpDatabase будет вызвана после выполнения всех тестов.

Если afterAll находится внутри блока describe, она выполняется в конце блока describe.

Если вместо выполнения после всех тестов нужно выполнять очистку после каждого теста, используйте afterEach.

afterEach(fn, timeout)

Запускает функцию после завершения каждого теста в этом файле. Если функция возвращает промис или является генератором, Jest дожидается разрешения этого промиса, прежде чем продолжить.

При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Это часто полезно, если нужно очистить временное состояние, создаваемое каждым тестом.

Например:

const globalDatabase = makeGlobalDatabase();

function cleanUpDatabase(db) {
  db.cleanUp();
}

afterEach(() => {
  cleanUpDatabase(globalDatabase);
});

test('can find things', () => {
  return globalDatabase.find('thing', {}, results => {
    expect(results.length).toBeGreaterThan(0);
  });
});

test('can insert a thing', () => {
  return globalDatabase.insert('thing', makeThing(), response => {
    expect(response.success).toBeTruthy();
  });
});

Здесь afterEach гарантирует, что cleanUpDatabase будет вызвана после каждого теста.

Если afterEach находится внутри блока describe, она выполняется только после тестов, находящихся внутри этого блока describe.

Если нужно выполнить очистку только один раз, после завершения всех тестов, используйте afterAll.

beforeAll(fn, timeout)

Запускает функцию перед выполнением любых тестов в этом файле. Если функция возвращает промис или является генератором, Jest дожидается разрешения этого промиса, прежде чем запускать тесты.

При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Это часто полезно, если нужно настроить некоторое глобальное состояние, которое будет использоваться многими тестами.

Например:

const globalDatabase = makeGlobalDatabase();

beforeAll(() => {
  // Clears the database and adds some testing data.
  // Jest will wait for this promise to resolve before running tests.
  return globalDatabase.clear().then(() => {
    return globalDatabase.insert({testData: 'foo'});
  });
});

// Since we only set up the database once in this example, it's important
// that our tests don't modify it.
test('can find things', () => {
  return globalDatabase.find('thing', {}, results => {
    expect(results.length).toBeGreaterThan(0);
  });
});

Здесь beforeAll гарантирует, что база данных будет настроена до запуска тестов. Если бы настройка выполнялась синхронно, можно было бы обойтись без beforeAll. Главное, что Jest будет ждать разрешения промиса, поэтому настройка может быть и асинхронной.

Если beforeAll находится внутри блока describe, она выполняется в начале блока describe.

Если вместо выполнения перед запуском любых тестов нужно выполнять что-либо перед каждым тестом, используйте beforeEach.

beforeEach(fn, timeout)

Запускает функцию перед каждым тестом в этом файле. Если функция возвращает промис или является генератором, Jest дожидается разрешения этого промиса, прежде чем запускать тест.

При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Это часто полезно, если нужно сбрасывать некоторое глобальное состояние, которое будет использоваться многими тестами.

Например:

const globalDatabase = makeGlobalDatabase();

beforeEach(() => {
  // Clears the database and adds some testing data.
  // Jest will wait for this promise to resolve before running tests.
  return globalDatabase.clear().then(() => {
    return globalDatabase.insert({testData: 'foo'});
  });
});

test('can find things', () => {
  return globalDatabase.find('thing', {}, results => {
    expect(results.length).toBeGreaterThan(0);
  });
});

test('can insert a thing', () => {
  return globalDatabase.insert('thing', makeThing(), response => {
    expect(response.success).toBeTruthy();
  });
});

Здесь beforeEach гарантирует, что база данных будет сбрасываться перед каждым тестом.

Если beforeEach находится внутри блока describe, она выполняется перед каждым тестом в блоке describe.

Если нужно выполнить код настройки только один раз, до запуска всех тестов, используйте beforeAll.

describe(name, fn)

describe(name, fn) создаёт блок, объединяющий несколько связанных тестов. Например, если у вас есть объект myBeverage, который должен быть вкусным, но не кислым, его можно протестировать так:

const myBeverage = {
  delicious: true,
  sour: false,
};

describe('my beverage', () => {
  test('is delicious', () => {
    expect(myBeverage.delicious).toBeTruthy();
  });

  test('is not sour', () => {
    expect(myBeverage.sour).toBeFalsy();
  });
});

Это необязательно — блоки test можно писать непосредственно на верхнем уровне. Но это может быть удобно, если вы предпочитаете группировать тесты.

Если тесты образуют иерархию, можно также вкладывать блоки describe друг в друга:

const binaryStringToNumber = binString => {
  if (!/^[01]+$/.test(binString)) {
    throw new CustomError('Not a binary number.');
  }

  return parseInt(binString, 2);
};

describe('binaryStringToNumber', () => {
  describe('given an invalid binary string', () => {
    test('composed of non-numbers throws CustomError', () => {
      expect(() => binaryStringToNumber('abc')).toThrow(CustomError);
    });

    test('with extra whitespace throws CustomError', () => {
      expect(() => binaryStringToNumber('  100')).toThrow(CustomError);
    });
  });

  describe('given a valid binary string', () => {
    test('returns the correct number', () => {
      expect(binaryStringToNumber('100')).toBe(4);
    });
  });
});

describe.each(table)(name, fn, timeout)

Используйте describe.each, если вы дублируете одни и те же наборы тестов с разными данными. describe.each позволяет написать набор тестов один раз и передавать в него данные.

Для describe.each доступны два API:

1. describe.each(table)(name, fn, timeout)

• table: Array массивов с аргументами, передаваемыми в fn для каждой строки. Если передать одномерный массив примитивов, внутри он будет преобразован в таблицу, то есть [1, 2, 3] -> [[1], [2], [3]].

• name: String заголовок набора тестов.

  • Создавайте уникальные заголовки тестов, позиционно подставляя параметры с помощью форматирования printf:
    • %p — pretty-format.
    • %s — строка.
    • %d — число.
    • %i — целое число.
    • %f — число с плавающей точкой.
    • %j — JSON.
    • %o — объект.
    • %# — индекс тестового случая.
    • %$ — номер тестового случая.
    • %% — одиночный знак процента ('%'). Аргумент при этом не используется.
  • Или создавайте уникальные заголовки тестов, подставляя свойства объекта тестового случая с помощью $variable
    • Чтобы подставить значения вложенных объектов, можно указать путь к ключу, например $variable.path.to.value (работает только для собственных свойств; например, $variable.constructor.name работать не будет)
    • Для подстановки индекса тестового случая можно использовать $#
    • Нельзя использовать $variable с форматированием printf, за исключением %%

• fn: Function набор тестов, который нужно запустить; эта функция получит параметры каждой строки в качестве аргументов.

• При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания для каждой строки перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Пример:

describe.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });

  test(`returned value not be greater than ${expected}`, () => {
    expect(a + b).not.toBeGreaterThan(expected);
  });

  test(`returned value not be less than ${expected}`, () => {
    expect(a + b).not.toBeLessThan(expected);
  });
});

describe.each([
  {a: 1, b: 1, expected: 2},
  {a: 1, b: 2, expected: 3},
  {a: 2, b: 1, expected: 3},
])('.add($a, $b)', ({a, b, expected}) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });

  test(`returned value not be greater than ${expected}`, () => {
    expect(a + b).not.toBeGreaterThan(expected);
  });

  test(`returned value not be less than ${expected}`, () => {
    expect(a + b).not.toBeLessThan(expected);
  });
});

2. describe.each`table`(name, fn, timeout)

• table: Tagged Template Literal
  • Первая строка содержит заголовки столбцов с именами переменных, разделённые |
  • Одна или несколько последующих строк содержат данные, передаваемые как выражения шаблонного литерала с использованием синтаксиса ${value}.
• name: String заголовок набора тестов; используйте $variable для подстановки тестовых данных из помеченных выражений шаблонного литерала в заголовок набора и $# для индекса строки.
  • Чтобы подставить значения вложенных объектов, можно указать путь к ключу, например $variable.path.to.value (работает только для собственных свойств; например, $variable.constructor.name работать не будет)
• fn: Function набор тестов, который нужно запустить; эта функция получит объект тестовых данных.
• При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания для каждой строки перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Пример:

describe.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('$a + $b', ({a, b, expected}) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });

  test(`returned value not be greater than ${expected}`, () => {
    expect(a + b).not.toBeGreaterThan(expected);
  });

  test(`returned value not be less than ${expected}`, () => {
    expect(a + b).not.toBeLessThan(expected);
  });
});

describe.only(name, fn)

Также доступно под псевдонимом: fdescribe(name, fn)

Если нужно запустить только один блок describe, можно использовать describe.only:

describe.only('my beverage', () => {
  test('is delicious', () => {
    expect(myBeverage.delicious).toBeTruthy();
  });

  test('is not sour', () => {
    expect(myBeverage.sour).toBeFalsy();
  });
});

describe('my other beverage', () => {
  // ... will be skipped
});

describe.only.each(table)(name, fn)

Также доступно под псевдонимами: fdescribe.each(table)(name, fn) и fdescribe.each`table`(name, fn)

Используйте describe.only.each, если нужно запустить только определённые наборы тестов из тестов, управляемых данными.

Для describe.only.each доступны два API:

describe.only.each(table)(name, fn)

describe.only.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

test('will not be run', () => {
  expect(1 / 0).toBe(Infinity);
});

describe.only.each`table`(name, fn)

describe.only.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('returns $expected when $a is added to $b', ({a, b, expected}) => {
  test('passes', () => {
    expect(a + b).toBe(expected);
  });
});

test('will not be run', () => {
  expect(1 / 0).toBe(Infinity);
});

describe.skip(name, fn)

Также доступно под псевдонимом: xdescribe(name, fn)

Если не нужно запускать тесты определённого блока describe, можно использовать describe.skip:

describe('my beverage', () => {
  test('is delicious', () => {
    expect(myBeverage.delicious).toBeTruthy();
  });

  test('is not sour', () => {
    expect(myBeverage.sour).toBeFalsy();
  });
});

describe.skip('my other beverage', () => {
  // ... will be skipped
});

Использование describe.skip часто является более аккуратной альтернативой временному комментированию фрагмента тестов. Учтите, что блок describe всё равно будет выполнен. Если нужно также пропустить какую-либо настройку, поместите её в блок beforeAll или beforeEach.

describe.skip.each(table)(name, fn)

Также доступно под псевдонимами: xdescribe.each(table)(name, fn) и xdescribe.each`table`(name, fn)

Используйте describe.skip.each, если нужно прекратить запуск набора тестов, управляемых данными.

Для describe.skip.each доступны два API:

describe.skip.each(table)(name, fn)

describe.skip.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected); // will not be run
  });
});

test('will be run', () => {
  expect(1 / 0).toBe(Infinity);
});

describe.skip.each`table`(name, fn)

describe.skip.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('returns $expected when $a is added to $b', ({a, b, expected}) => {
  test('will not be run', () => {
    expect(a + b).toBe(expected); // will not be run
  });
});

test('will be run', () => {
  expect(1 / 0).toBe(Infinity);
});

test(name, fn, timeout)

Также доступно под псевдонимом: it(name, fn, timeout)

В файле тестов достаточно использовать метод test, который запускает тест. Например, допустим, есть функция inchesOfRain(), результат которой должен быть равен нулю. Тест может выглядеть так:

test('did not rain', () => {
  expect(inchesOfRain()).toBe(0);
});

Первый аргумент — имя теста; второй — функция, содержащая проверяемые утверждения. Третий аргумент (необязательный) — timeout (в миллисекундах), задающий время ожидания перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Если test возвращает промис, Jest дождётся его разрешения, прежде чем завершить тест. Например, допустим, fetchBeverageList() возвращает промис, который должен разрешиться в список, содержащий lemon. Это можно проверить так:

test('has lemon in it', () => {
  return fetchBeverageList().then(list => {
    expect(list).toContain('lemon');
  });
});

Хотя вызов test сразу же вернёт управление, тест не завершится, пока не разрешится промис. Подробнее см. на странице Тестирование асинхронного кода.

test.concurrent(name, fn, timeout)

Также доступно под псевдонимом: it.concurrent(name, fn, timeout)

Используйте test.concurrent, если хотите, чтобы тест выполнялся параллельно с другими.

Первый аргумент — имя теста; второй — асинхронная функция, содержащая проверяемые утверждения. Третий аргумент (необязательный) — timeout (в миллисекундах), задающий время ожидания перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

test.concurrent('addition of 2 numbers', async () => {
  expect(5 + 3).toBe(8);
});

test.concurrent('subtraction 2 numbers', async () => {
  expect(5 - 3).toBe(2);
});

test.concurrent.each(table)(name, fn, timeout)

Также доступно под псевдонимом: it.concurrent.each(table)(name, fn, timeout)

Используйте test.concurrent.each, если вы дублируете один и тот же тест с разными данными. test.each позволяет написать тест один раз и передавать в него данные; все тесты запускаются асинхронно.

Для test.concurrent.each доступны два API:

1. test.concurrent.each(table)(name, fn, timeout)

• table: Array массивов с аргументами, передаваемыми в тест fn для каждой строки. Если передать одномерный массив примитивов, внутри он будет преобразован в таблицу, то есть [1, 2, 3] -> [[1], [2], [3]]
• name: String заголовок блока тестов.
  • Создавайте уникальные заголовки тестов, позиционно подставляя параметры с помощью форматирования printf:
    • %p — pretty-format.
    • %s — строка.
    • %d — число.
    • %i — целое число.
    • %f — число с плавающей точкой.
    • %j — JSON.
    • %o — объект.
    • %# — индекс тестового случая.
    • %$ — номер тестового случая.
    • %% — одиночный знак процента ('%'). Аргумент при этом не используется.
• fn: Function тест, который нужно запустить; эта функция получит параметры каждой строки в качестве аргументов. Это должна быть асинхронная функция.
• При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания для каждой строки перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Пример:

test.concurrent.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('.add(%i, %i)', async (a, b, expected) => {
  expect(a + b).toBe(expected);
});

2. test.concurrent.each`table`(name, fn, timeout)

• table: Tagged Template Literal
  • Первая строка содержит заголовки столбцов с именами переменных, разделённые |
  • Одна или несколько последующих строк содержат данные, передаваемые как выражения шаблонного литерала с использованием синтаксиса ${value}.
• name: String заголовок теста; используйте $variable для подстановки тестовых данных из помеченных выражений шаблонного литерала в заголовок теста.
  • Чтобы подставить значения вложенных объектов, можно указать путь к ключу, например $variable.path.to.value (работает только для собственных свойств; например, $variable.constructor.name работать не будет)
• fn: Function тест, который нужно запустить; эта функция получит объект тестовых данных. Это должна быть асинхронная функция.
• При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания для каждой строки перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Пример:

test.concurrent.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('returns $expected when $a is added to $b', async ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

test.concurrent.only.each(table)(name, fn)

Также доступно под псевдонимом: it.concurrent.only.each(table)(name, fn)

Используйте test.concurrent.only.each, если нужно параллельно запускать только определённые тесты с разными тестовыми данными.

Для test.concurrent.only.each доступны два API:

test.concurrent.only.each(table)(name, fn)

test.concurrent.only.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('.add(%i, %i)', async (a, b, expected) => {
  expect(a + b).toBe(expected);
});

test('will not be run', () => {
  expect(1 / 0).toBe(Infinity);
});

test.only.each`table`(name, fn)

test.concurrent.only.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('returns $expected when $a is added to $b', async ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

test('will not be run', () => {
  expect(1 / 0).toBe(Infinity);
});

test.concurrent.skip.each(table)(name, fn)

Также доступно под псевдонимом: it.concurrent.skip.each(table)(name, fn)

Используйте test.concurrent.skip.each, если нужно прекратить запуск набора асинхронных тестов, управляемых данными.

Для test.concurrent.skip.each доступны два API:

test.concurrent.skip.each(table)(name, fn)

test.concurrent.skip.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('.add(%i, %i)', async (a, b, expected) => {
  expect(a + b).toBe(expected); // will not be run
});

test('will be run', () => {
  expect(1 / 0).toBe(Infinity);
});

test.concurrent.skip.each`table`(name, fn)

test.concurrent.skip.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('returns $expected when $a is added to $b', async ({a, b, expected}) => {
  expect(a + b).toBe(expected); // will not be run
});

test('will be run', () => {
  expect(1 / 0).toBe(Infinity);
});

test.each(table)(name, fn, timeout)

Также доступно под псевдонимами: it.each(table)(name, fn) и it.each`table`(name, fn)

Используйте test.each, если вы дублируете один и тот же тест с разными данными. test.each позволяет написать тест один раз и передавать в него данные.

Для test.each доступны два API:

1. test.each(table)(name, fn, timeout)

• table: Array массивов с аргументами, передаваемыми в тест fn для каждой строки. Если передать одномерный массив примитивов, внутри он будет преобразован в таблицу, то есть [1, 2, 3] -> [[1], [2], [3]]
• name: String заголовок блока тестов.
  • Создавайте уникальные заголовки тестов, позиционно подставляя параметры с помощью форматирования printf:
    • %p — pretty-format.
    • %s — строка.
    • %d — число.
    • %i — целое число.
    • %f — число с плавающей точкой.
    • %j — JSON.
    • %o — объект.
    • %# — индекс тестового случая.
    • %$ — номер тестового случая.
    • %% — одиночный знак процента ('%'). Аргумент при этом не используется.
  • Или создавайте уникальные заголовки тестов, подставляя свойства объекта тестового случая с помощью $variable
    • Чтобы подставить значения вложенных объектов, можно указать путь к ключу, например $variable.path.to.value (работает только для собственных свойств; например, $variable.constructor.name работать не будет)
    • Для подстановки индекса тестового случая можно использовать $#
    • Нельзя использовать $variable с форматированием printf, за исключением %%
• fn: Function тест, который нужно запустить; эта функция получит параметры каждой строки в качестве аргументов.
• При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания для каждой строки перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Пример:

test.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
  expect(a + b).toBe(expected);
});

test.each([
  {a: 1, b: 1, expected: 2},
  {a: 1, b: 2, expected: 3},
  {a: 2, b: 1, expected: 3},
])('.add($a, $b)', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

2. test.each`table`(name, fn, timeout)

• table: Tagged Template Literal
  • Первая строка содержит заголовки столбцов с именами переменных, разделённые |
  • Одна или несколько последующих строк содержат данные, передаваемые как выражения шаблонного литерала с использованием синтаксиса ${value}.
• name: String заголовок теста; используйте $variable для подстановки тестовых данных из помеченных выражений шаблонного литерала в заголовок теста.
  • Чтобы подставить значения вложенных объектов, можно указать путь к ключу, например $variable.path.to.value (работает только для собственных свойств; например, $variable.constructor.name работать не будет)
• fn: Function тест, который нужно запустить; эта функция получит объект тестовых данных.
• При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания для каждой строки перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Пример:

test.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('returns $expected when $a is added to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

test.failing(name, fn, timeout)

Также доступно под псевдонимом: it.failing(name, fn, timeout)

Используйте test.failing при написании теста, который должен завершиться неудачей. Эти тесты ведут себя противоположно обычным. Если тест failing выбросит ошибку, он пройдёт. Если ошибка не будет выброшена, тест завершится неудачей.

Пример:

test.failing('it is not equal', () => {
  expect(5).toBe(6); // this test will pass
});

test.failing('it is equal', () => {
  expect(10).toBe(10); // this test will fail
});

test.failing.each(name, fn, timeout)

Также доступно под псевдонимами: it.failing.each(table)(name, fn) и it.failing.each`table`(name, fn)

Также можно запускать несколько тестов одновременно, добавив each после failing.

Пример:

test.failing.each([
  {a: 1, b: 1, expected: 2},
  {a: 1, b: 2, expected: 3},
  {a: 2, b: 1, expected: 3},
])('.add($a, $b)', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

test.only.failing(name, fn, timeout)

Также доступно под псевдонимами: it.only.failing(name, fn, timeout), fit.failing(name, fn, timeout)

Используйте test.only.failing, если нужно запустить только один конкретный тест, завершающийся неудачей.

test.skip.failing(name, fn, timeout)

Также доступно под псевдонимами: it.skip.failing(name, fn, timeout), xit.failing(name, fn, timeout), xtest.failing(name, fn, timeout)

Используйте test.skip.failing, если нужно пропустить запуск конкретного теста, завершающегося неудачей.

test.only(name, fn, timeout)

Также доступно под псевдонимами: it.only(name, fn, timeout) и fit(name, fn, timeout)

При отладке большого файла тестов часто требуется запустить только часть тестов. С помощью .only можно указать, какие тесты нужно запускать в этом файле.

При необходимости можно указать timeout (в миллисекундах), чтобы задать время ожидания перед прерыванием. По умолчанию тайм-аут составляет 5 секунд.

Например, допустим, у вас есть следующие тесты:

test.only('it is raining', () => {
  expect(inchesOfRain()).toBeGreaterThan(0);
});

test('it is not snowing', () => {
  expect(inchesOfSnow()).toBe(0);
});

В этом файле тестов будет запущен только тест «идёт дождь», поскольку для него используется test.only.

Обычно код с test.only не добавляют в систему контроля версий — его используют для отладки и удаляют после исправления неработающих тестов.

test.only.each(table)(name, fn)

Также известны под псевдонимами: it.only.each(table)(name, fn), fit.each(table)(name, fn), it.only.each`table`(name, fn) и fit.each`table`(name, fn)

Используйте test.only.each, если хотите запускать только определённые тесты с разными тестовыми данными.

test.only.each доступен с двумя API:

test.only.each(table)(name, fn)

test.only.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
  expect(a + b).toBe(expected);
});

test('will not be run', () => {
  expect(1 / 0).toBe(Infinity);
});

test.only.each`table`(name, fn)

test.only.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('returns $expected when $a is added to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

test('will not be run', () => {
  expect(1 / 0).toBe(Infinity);
});

test.skip(name, fn)

Также известны под псевдонимами: it.skip(name, fn), xit(name, fn) и xtest(name, fn)

При работе с большой кодовой базой вы иногда можете обнаружить тест, который временно не работает по какой-либо причине. Если вы хотите пропустить запуск этого теста, но не хотите удалять код, используйте test.skip, чтобы указать тесты, которые нужно пропустить.

Например, предположим, у вас есть такие тесты:

test('it is raining', () => {
  expect(inchesOfRain()).toBeGreaterThan(0);
});

test.skip('it is not snowing', () => {
  expect(inchesOfSnow()).toBe(0);
});

Запустится только тест «идёт дождь», поскольку для другого теста используется test.skip.

Вы можете закомментировать тест, но зачастую удобнее использовать test.skip, поскольку при этом сохраняются отступы и подсветка синтаксиса.

test.skip.each(table)(name, fn)

Также известны под псевдонимами: it.skip.each(table)(name, fn), xit.each(table)(name, fn), xtest.each(table)(name, fn), it.skip.each`table`(name, fn), xit.each`table`(name, fn) и xtest.each`table`(name, fn)

Используйте test.skip.each, если хотите прекратить запуск набора тестов с данными.

test.skip.each доступен с двумя API:

test.skip.each(table)(name, fn)

test.skip.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
  expect(a + b).toBe(expected); // will not be run
});

test('will be run', () => {
  expect(1 / 0).toBe(Infinity);
});

test.skip.each`table`(name, fn)

test.skip.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('returns $expected when $a is added to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected); // will not be run
});

test('will be run', () => {
  expect(1 / 0).toBe(Infinity);
});

test.todo(name)

Также известны под псевдонимом: it.todo(name)

Используйте test.todo, если планируете писать тесты. Эти тесты будут выделены в итоговой сводке, чтобы вы знали, сколько тестов ещё нужно написать.

const add = (a, b) => a + b;

test.todo('add should be associative');

Использование TypeScript

import {expect, jest, test} from '@jest/globals';

.each

Модификатор .each позволяет несколькими способами задать таблицу тестовых случаев. У некоторых API есть нюансы, связанные с выводом типов аргументов, передаваемых функциям обратного вызова describe или test. Рассмотрим каждый из них.

Массив объектов

API массива объектов наиболее многословен, но благодаря ему вывод типов не вызывает затруднений. table можно объявить непосредственно:

import {test} from '@jest/globals';

test.each([
  {name: 'a', path: 'path/to/a', count: 1, write: true},
  {name: 'b', path: 'path/to/b', count: 3},
])('inline table', ({name, path, count, write}) => {
  // arguments are typed as expected, e.g. `write: boolean | undefined`
});

Или объявить отдельно в виде переменной:

import {test} from '@jest/globals';

const table = [
  {a: 1, b: 2, expected: 'three', extra: true},
  {a: 3, b: 4, expected: 'seven', extra: false},
  {a: 5, b: 6, expected: 'eleven'},
];

test.each(table)('table as a variable', ({a, b, expected, extra}) => {
  // again everything is typed as expected, e.g. `extra: boolean | undefined`
});

Массив массивов

Формат массива массивов хорошо работает с таблицами, объявленными непосредственно:

import {test} from '@jest/globals';

test.each([
  [1, 2, 'three', true],
  [3, 4, 'seven', false],
  [5, 6, 'eleven'],
])('inline table example', (a, b, expected, extra) => {
  // arguments are typed as expected, e.g. `extra: boolean | undefined`
});

Однако если таблица объявлена как отдельная переменная, для корректного вывода типов её необходимо типизировать как массив кортежей (это не требуется, только если все элементы строки имеют одинаковый тип):

import {test} from '@jest/globals';

const table: Array<[number, number, string, boolean?]> = [
  [1, 2, 'three', true],
  [3, 4, 'seven', false],
  [5, 6, 'eleven'],
];

test.each(table)('table as a variable example', (a, b, expected, extra) => {
  // without the annotation types are incorrect, e.g. `a: number | string | boolean`
});

Шаблонный литерал

Если все входные значения имеют один тип, API шаблонных литералов правильно определит типы аргументов:

import {test} from '@jest/globals';

test.each`
  a    | b    | expected
  ${1} | ${2} | ${3}
  ${3} | ${4} | ${7}
  ${5} | ${6} | ${11}
`('template literal example same type', ({a, b, expected}) => {
  // all arguments are of type `number` because all inputs (a, b, expected) are of type `number`
});

Если входные значения имеют разные типы, тип аргументов будет определён как объединение всех типов входных значений (то есть типов переменных внутри шаблонного литерала):

import {test} from '@jest/globals';

test.each`
  a    | b    | expected
  ${1} | ${2} | ${'three'}
  ${3} | ${4} | ${'seven'}
  ${5} | ${6} | ${'eleven'}
`('template literal example different types', ({a, b, expected}) => {
  // all arguments are of type `number | string` because some inputs (a, b) are of type `number` and some others (expected) are of type `string`
});

В противном случае, если вы хотите, чтобы тип каждого аргумента был определён правильно, необходимо явно указать аргумент обобщённого типа:

import {test} from '@jest/globals';

test.each<{a: number; b: number; expected: string; extra?: boolean}>`
  a    | b    | expected    | extra
  ${1} | ${2} | ${'three'}  | ${true}
  ${3} | ${4} | ${'seven'}  | ${false}
  ${5} | ${6} | ${'eleven'}
`('template literal example', ({a, b, expected, extra}) => {
  // all arguments are typed as expected, e.g. `a: number`, `expected: string`, `extra: boolean | undefined`
});

import {test} from '@jest/globals';

test.each<{a: number; expected: string}>`
  a                            | expected
  ${1}                         | ${'one'}
  ${'will not raise TS error'} | ${'two'}
  ${3}                         | ${'three'}
`('template literal with wrongly typed input', ({a, expected}) => {
  // all arguments are typed as stated in the generic: `a: number`, `expected: string`
  // WARNING: `a` is of type `number` but will be a string in the 2nd test case.
});