Skip to main content
Versão: Próximo

Globais

O Jest coloca cada um desses métodos e objetos no ambiente global dos seus arquivos de teste. Você não precisar fazer nenhuma importação para poder usá-los. No entanto, se você prefere importá-los explicitamente, basta escrever import {describe, expect, test} from '@jest/globals'.

informação

Os exemplos de TypeScript desta página só funcionarão como documentados se você importar explicitamente APIs do Jest:

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

Consulte o guia Iniciando para obter detalhes sobre como configurar Jest com TypeScript.

Métodos​

Referência​

afterAll(fn, timeout)​

Executa uma função depois que todos os testes neste arquivo forem concluídos. Se a função retorna uma promise ou é um generator, Jest aguarda essa promise resolver antes de continuar.

Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar. The default timeout is 5 seconds.

Por exemplo:

Por exemplo:

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();
  });
});

Se afterAll está dentro de um bloco describe, ele é executado ao final do bloco "describe".

Se você deseja executar uma limpeza após cada teste em vez de após todos os testes, use ao invés afterEach.

Se você deseja executar uma limpeza após cada teste em vez de após todos os testes, use ao invés afterEach.

afterEach(fn, timeout)​

Executa uma função após cada um dos testes deste arquivo completar. Se a função retorna uma promise ou é um generator, Jest aguarda essa promise resolver antes de continuar.

Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar. The default timeout is 5 seconds.

Por exemplo:

Por exemplo:

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();
  });
});

Se afterEach está dentro de um bloco describe, ele é executado somente após os testes que estão dentro deste bloco "describe".

Se você deseja executar uma limpeza apenas uma vez, depois que todos os testes são executados, use afterAll.

Se você deseja executar uma limpeza apenas uma vez, depois que todos os testes são executados, use afterAll.

beforeAll(fn, timeout)​

Executa uma função antes de qualquer um dos testes neste arquivo ser executado. Se a função retornar uma promise ou for um generator, o Jest vai esperar até que ela esteja resolvida para executar os testes.

Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar. The default timeout is 5 seconds.

Por exemplo:

Por exemplo:

const globalDatabase = makeGlobalDatabase();

beforeAll(() => {
  // Limpa o banco de dados e adiciona alguns dados de teste.
  // O Jest aguardará que essa promessa seja resolvida antes de executar os testes.
  return globalDatabase.clear().then(() => {
    return globalDatabase.insert({testData: 'foo'});
  });
});

  // Jest irá esperar que essa promessa seja resolvida antes de executar testes.
  // Como configuramos o banco de dados apenas uma vez neste exemplo, é importante
//que nossos testes não o modifiquem.
test('can find things', () => {
  return globalDatabase.find('thing', {}, results => {
    expect(results.length).toBeGreaterThan(0);
  });
});

Aqui beforeAll garante que o banco de dados está configurado antes dos testes serem executados. Se a configuração for síncrona, você pode fazer tudo sem precisar usar o beforeAll. A chave é que Jest esperará por uma promessa resolver, para que você possa ter configuração assíncrona também.

Se você deseja executar algo antes de cada teste, em vez de antes que qualquer teste seja executado, use beforeEach.

Se você deseja executar algo antes de cada teste, em vez de antes que qualquer teste seja executado, use beforeEach.

beforeEach(fn, timeout)​

Executa uma função antes que cada um dos testes neste arquivo seja executado. Se a função retornar uma promise ou for um generator, o Jest vai esperar até que ela esteja resolvida para executar os testes.

Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar. The default timeout is 5 seconds.

Por exemplo:

Por exemplo:

const globalDatabase = makeGlobalDatabase();

beforeEach(() => {
  // Clears the database and adds some testing data.
  // Jest irá esperar que essa promessa seja resolvida antes de executar testes.
  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);
  });
});

Se beforeEach está dentro de um bloco describe, ele é executado para cada teste no bloco "describe".

Se você só precisa executar algum código de configuração uma vez, antes que qualquer teste execute, use ao invés beforeAll.

Se você só precisa executar algum código de configuração uma vez, antes que qualquer teste execute, use ao invés beforeAll.

describe(name, fn)​

describe(name, fn) cria um bloco que agrupa vários testes relacionados. Por exemplo, se você tiver um objeto myBeverage que deve ser delicioso, mas não azedo, você pode testá-lo com:

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

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

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

Isso não é necessário - você pode escrever os blocos de teste diretamente em nível superior. Mas isso pode ser útil se preferir que os seus testes sejam organizados em grupos.

Você também pode aninhar blocos describe se você tem uma hierarquia de testes:

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)​

Use describe.each se você continuar duplicando a mesma suíte de testes com dados diferentes. describe.each permite que você escreva a suíte de testes apenas uma vez passando os dados para cada execução.

describe.each está disponível com duas APIs:

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

  • table: Array de Arrays com os argumentos que serão passados à função do argumento fn de cada execução. If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. [1, 2, 3] -> [[1], [2], [3]].

  • name: String com o nome da suíte de testes.

    • Escreva títulos únicos para os testes injetando parâmetros na string com a formatação printf:
      • %p - pretty-format.
      • %s- String.
      • %d- Number.
      • %i - Integer.
      • %f - Floating point value.
      • %j - JSON.
      • %o - Object.
      • %# - Índice do caso de teste.
      • %$ - Number of the test case.
      • %% - sinal de porcentagem único ('%'). Isto não consome nenhum argumento.
    • Ou escreva títulos únicos ao injetar propriedades do objeto de teste com uma $variavel
      • Para injetar valores de objetos aninhados, você pode prover um keyPath, por exemplo: $variavel.caminho.do.valor
      • Você pode usar $# para injetar o índice do caso de teste
      • Você não pode usar uma $variavel com a formatação printf com a exceção de %%

  • fn: Function the suite of tests to be run, this is the function that will receive the parameters in each row as function arguments.

  • Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar a execução. The default timeout is 5 seconds.

Example:

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
    • A primeira linha é o cabeçalho que contém o nome das variáveis de cada coluna separadas por |
    • Uma ou mais linhas de dados declaradas como expressões de template literal usando a sintaxe ${value}.
  • name: String o título da suíte de testes. Use uma $variavel para injetar os dados declarados dentro da expressão tagged template no título da suíte e $# para acessar o índice de cada linha.
    • Para injetar valores de objetos aninhados, você pode prover um keyPath, por exemplo: $variavel.caminho.do.valor
  • fn: Function the suite of tests to be run, this is the function that will receive the test data object.
  • Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar a execução. The default timeout is 5 seconds.

Example:

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)​

Você pode usar describe.only se você deseja executar apenas um bloco "describe":

Se beforeAll está dentro de um bloco describe, ele é executado no início do bloco de "describe".

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)​

Também pode ser chamada com fdescribe.each(table)(name, fn) e fdescribe.each`table`(name, fn)

Use describe.only.each se você deseja executar apenas suítes específicas de testes orientadas a dados.

describe.only.each está disponível com duas APIs:

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)​

Também pode ser chamada com xdescribe(name, fn)

You can use describe.skip if you do not want to run the tests of a particular describe block:

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
});

Usar describe.skip muitas vezes é uma alternativa mais limpa de temporariamente pular um trecho do teste. Beware that the describe block will still run. If you have some setup that also should be skipped, do it in a beforeAll or beforeEach block.

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

Também pode ser chamada com xdescribe.each(table)(name, fn) e xdescribe.each`table`(name, fn)

Use describe.skip.each se você deseja parar a execução de uma suíte de testes orientada a dados.

describe.skip.each está disponível com duas APIs:

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)​

Também pode ser chamada com it(name, fn, timeout)

Tudo que você precisa em um arquivo de teste é o método test que executa um teste. Por exemplo, digamos que há uma função inchesOfRain() que deve ser zero. O teste inteiro poderia ser:

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

O primeiro argumento é o nome do teste; o segundo argumento é uma função que contém as expectativas para testar. O terceiro argumento (opcional) é o timeout (em milissegundos) que determina o tempo de espera antes da execução ser abortada. The default timeout is 5 seconds.

If a promise is returned from test, Jest will wait for the promise to resolve before letting the test complete. Por exemplo, digamos que a função fetchBeverageList() retorna uma promise que é esperada para resolver uma lista que contém o valor lemon nela. Você pode testar isso com:

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

Even though the call to test will return right away, the test doesn't complete until the promise resolves. For more details, see Testing Asynchronous Code page.

tip

O Jest também vai esperar caso você forneça um argumento para a função de teste, geralmente chamado done. This could be handy when you want to test callbacks.

test.concurrent(name, fn, timeout)​

Também pode ser chamada com it.concurrent(name, fn, timeout)

atenção

test.concurrent is considered experimental - see here for details on missing features and other issues.

Use test.concurrent se você quiser que o teste seja executado simultaneamente.

O primeiro argumento é o nome do teste; o segundo argumento é uma função que contém as asserções do teste. O terceiro argumento (opcional) é o timeout (em milissegundos) que determina o tempo de espera antes da execução ser abortada. The default timeout is 5 seconds.

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

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

Use the maxConcurrency configuration option to prevent Jest from executing more than the specified amount of tests at the same time.

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

Também pode ser chamada com it.concurrent.each(table)(name, fn, timeout)

Use test.concurrent.each se você duplica com frequência a mesma suíte de testes com dados diferentes. test.each permite que você escreva o teste uma vez passando os dados para cada execução, todos os testes são executados de forma assíncrona.

test.concurrent.each está disponível com duas APIs:

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

  • table: Array de Arrays com os argumentos que serão passados à função fn para cada execução. If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. [1, 2, 3] -> [[1], [2], [3]]
  • name: String com o nome do bloco de teste.
    • Escreva títulos únicos para os testes injetando parâmetros na string com a formatação printf:
      • %p - pretty-format.
      • %s- String.
      • %d- Number.
      • %i - Integer.
      • %f - Floating point value.
      • %j - JSON.
      • %o - Object.
      • %# - Índice do caso de teste.
      • %$ - Number of the test case.
      • %% - sinal de porcentagem único ('%'). Isto não consome nenhum argumento.
  • fn: Function the test to be run, this is the function that will receive the parameters in each row as function arguments, this will have to be an asynchronous function.
  • Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar a execução. The default timeout is 5 seconds.

Example:

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
    • A primeira linha é o cabeçalho que contém o nome das variáveis de cada coluna separadas por |
    • Uma ou mais linhas de dados declaradas como expressões de template literal usando a sintaxe ${value}.
  • name: String o título do teste. Use uma $variavel para injetar os dados declarados dentro da expressão tagged template no título do teste.
    • Para injetar valores de objetos aninhados, você pode prover um keyPath, por exemplo: $variavel.caminho.do.valor
  • fn: Function the test to be run, this is the function that will receive the test data object, this will have to be an asynchronous function.
  • Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar a execução. The default timeout is 5 seconds.

Example:

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)​

Também pode ser chamada com it.concurrent.only.each(table)(name, fn)

Use test.concurrent.only.each if you want to only run specific tests with different test data concurrently.

test.concurrent.only.each is available with two APIs:

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)​

Also under the alias: it.concurrent.skip.each(table)(name, fn)

Use test.concurrent.skip.each if you want to stop running a collection of asynchronous data driven tests.

test.concurrent.skip.each is available with two APIs:

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)​

Also under the alias: it.each(table)(name, fn) and it.each`table`(name, fn)

Use test.each if you keep duplicating the same test with different data. test.each allows you to write the test once and pass data in.

test.each is available with two APIs:

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

  • table: Array de Arrays com os argumentos que serão passados à função fn para cada execução. If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. [1, 2, 3] -> [[1], [2], [3]]
  • name: String com o nome do bloco de teste.
    • Escreva títulos únicos para os testes injetando parâmetros na string com a formatação printf:
      • %p - pretty-format.
      • %s- String.
      • %d- Number.
      • %i - Integer.
      • %f - Floating point value.
      • %j - JSON.
      • %o - Object.
      • %# - Índice do caso de teste.
      • %$ - Number of the test case.
      • %% - sinal de porcentagem único ('%'). Isto não consome nenhum argumento.
    • Ou escreva títulos únicos ao injetar propriedades do objeto de teste com uma $variavel
      • Para injetar valores de objetos aninhados, você pode prover um keyPath, por exemplo: $variavel.caminho.do.valor
      • Você pode usar $# para injetar o índice do caso de teste
      • Você não pode usar uma $variavel com a formatação printf com a exceção de %%
  • fn: Function the test to be run, this is the function that will receive the parameters in each row as function arguments.
  • Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar a execução. The default timeout is 5 seconds.

Example:

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
    • A primeira linha é o cabeçalho que contém o nome das variáveis de cada coluna separadas por |
    • Uma ou mais linhas de dados declaradas como expressões de template literal usando a sintaxe ${value}.
  • name: String o título do teste. Use uma $variavel para injetar os dados declarados dentro da expressão tagged template no título do teste.
    • Para injetar valores de objetos aninhados, você pode prover um keyPath, por exemplo: $variavel.caminho.do.valor
  • fn: Function the test to be run, this is the function that will receive the test data object.
  • Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar a execução. The default timeout is 5 seconds.

Example:

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)​

Also under the alias: it.failing(name, fn, timeout)

note

This is only available with the default jest-circus runner.

Use test.failing when you are writing a test and expecting it to fail. These tests will behave the other way normal tests do. If failing test will throw any errors then it will pass. If it does not throw it will fail.

tip

You can use this type of test i.e. when writing code in a BDD way. In that case the tests will not show up as failing until they pass. Then you can just remove the failing modifier to make them pass.

It can also be a nice way to contribute failing tests to a project, even if you don't know how to fix the bug.

Example:

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)​

Also under the alias: it.failing.each(table)(name, fn) and it.failing.each`table`(name, fn)

note

This is only available with the default jest-circus runner.

You can also run multiple tests at once by adding each after failing.

Example:

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)​

Also under the aliases: it.only.failing(name, fn, timeout), fit.failing(name, fn, timeout)

note

This is only available with the default jest-circus runner.

Use test.only.failing if you want to only run a specific failing test.

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

Also under the aliases: it.skip.failing(name, fn, timeout), xit.failing(name, fn, timeout), xtest.failing(name, fn, timeout)

note

This is only available with the default jest-circus runner.

Use test.skip.failing if you want to skip running a specific failing test.

test.only(name, fn, timeout)​

Also under the aliases: it.only(name, fn, timeout), and fit(name, fn, timeout)

When you are debugging a large test file, you will often only want to run a subset of tests. You can use .only to specify which tests are the only ones you want to run in that test file.

Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar. The default timeout is 5 seconds.

Por exemplo, digamos que você tenha estes testes:

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

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

Only the "it is raining" test will run in that test file, since it is run with test.only.

Usually you wouldn't check code using test.only into source control - you would use it for debugging, and remove it once you have fixed the broken tests.

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

Also under the aliases: it.only.each(table)(name, fn), fit.each(table)(name, fn), it.only.each`table`(name, fn) and fit.each`table`(name, fn)

Use test.only.each if you want to only run specific tests with different test data.

test.only.each is available with two APIs:

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)​

Also under the aliases: it.skip(name, fn), xit(name, fn), and xtest(name, fn)

Quando você está mantendo uma grande base de código, você pode às vezes encontrar um teste que está quebrado temporariamente por algum motivo. If you want to skip running this test, but you don't want to delete this code, you can use test.skip to specify some tests to skip.

Por exemplo, digamos que você tenha estes testes:

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

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

Somente o teste "it is raining" será executado, já que o outro teste é executado com test.skip.

You could comment the test out, but it's often a bit nicer to use test.skip because it will maintain indentation and syntax highlighting.

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

Also under the aliases: 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) and xtest.each`table`(name, fn)

Use test.skip.each if you want to stop running a collection of data driven tests.

test.skip.each is available with two APIs:

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)​

Also under the alias: it.todo(name)

Use test.todo when you are planning on writing tests. These tests will be highlighted in the summary output at the end so you know how many tests you still need todo.

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

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

test.todo will throw an error if you pass it a test callback function. Use test.skip instead, if you already implemented the test, but do not want it to run.

TypeScript Usage​

informação

Os exemplos de TypeScript desta página só funcionarão como documentados se você importar explicitamente APIs do Jest:

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

Consulte o guia Iniciando para obter detalhes sobre como configurar Jest com TypeScript.

.each​

The .each modifier offers few different ways to define a table of the test cases. Some of the APIs have caveats related with the type inference of the arguments which are passed to describe or test callback functions. Let's take a look at each of them.

note

For simplicity test.each is picked for the examples, but the type inference is identical in all cases where .each modifier can be used: describe.each, test.concurrent.only.each, test.skip.each, etc.

Array of objects​

The array of objects API is most verbose, but it makes the type inference a painless task. A table can be inlined:

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`
});

Or declared separately as a variable:

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`
});

Array of arrays​

The array of arrays style will work smoothly with inlined tables:

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`
});

However, if a table is declared as a separate variable, it must be typed as an array of tuples for correct type inference (this is not needed only if all elements of a row are of the same type):

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`
});

Template literal​

If all input values are of the same type, the template literal API will type the arguments correctly:

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`
});

If the inputs have different types, the arguments will be typed as a union of all the input types (i.e. type of the variables inside the template literal):

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`
});

Otherwise, if you want each argument to have the right type, you have to explicitly provide the generic type argument:

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`
});
atenção

Keep in mind the variables inside the template literal are not type checked, so you have to ensure that their types are correct.

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.
});