Skip to main content
Version: 25.x

Globais

In your test files, Jest puts each of these methods and objects into the global environment. You don't have to require or import anything to use them. However, if you prefer explicit imports, you can do import {describe, expect, test} from '@jest/globals'.

Métodos#


Reference#

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. Note: 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. Note: 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. If the function returns a promise or is a generator, Jest waits for that promise to resolve before running tests.

Opcionalmente, você pode fornecer um timeout (em milissegundos) para especificar quanto tempo esperar antes de abortar. Note: 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'});
});
});
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();
});
});

Aqui beforeAll garante que o banco de dados está configurado antes dos testes serem executados. If setup was synchronous, you could do this without 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. If the function returns a promise or is a generator, Jest waits for that promise to resolve before running the test.

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

Por exemplo:

Por exemplo:

const globalDatabase = makeGlobalDatabase();
beforeAll(() => {
// 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')).toThrowError(CustomError);
});
test('with extra whitespace throws CustomError', () => {
expect(() => binaryStringToNumber(' 100')).toThrowError(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 allows you to write the test suite once and pass data in.

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

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

  • table: Array of Arrays with the arguments that are passed into the fn for each row.
    • Note 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]]
  • nome: String the title of the test suite.
    • Generate unique test titles by positionally injecting parameters with printf formatting:
      • %p - pretty-format.
      • %s- String.
      • %d- Number.
      • %i - Integer.
      • %f - Floating point value.
      • %j - JSON.
      • %o - Object.
      • %# - Index of the test case.
      • %% - single percent sign ('%'). This does not consume an argument.
  • fn: Function the suite of tests to be ran, this is the function that will receive the parameters in each row as function arguments.
  • Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait for each row before aborting. Note: 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);
});
});

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

  • table: Tagged Template Literal
    • First row of variable name column headings separated with |
    • One or more subsequent rows of data supplied as template literal expressions using ${value} syntax.
  • nome: String the title of the test suite, use $variable to inject test data into the suite title from the tagged template expressions.
    • To inject nested object values use you can supply a keyPath i.e. $variable.path.to.value
  • fn: Function the suite of tests to be ran, this is the function that will receive the test data object.
  • Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait for each row before aborting. Note: 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)#

Also under the aliases: fdescribe.each(table)(name, fn) and fdescribe.each`table`(name, fn)

Use describe.only.each if you want to only run specific tests suites of data driven tests.

describe.only.each is available with two 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 ran', () => {
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 $b', ({a, b, expected}) => {
test('passes', () => {
expect(a + b).toBe(expected);
});
});
test('will not be ran', () => {
expect(1 / 0).toBe(Infinity);
});

describe.skip(name, fn)#

Você pode usar describe.skip se você não deseja executar um bloco específico "describe":

Você pode usar describe.skip se você não deseja executar um bloco específico "describe":

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

Using describe.skip is often a cleaner alternative to temporarily commenting out a chunk of tests.

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

Also under the aliases: xdescribe.each(table)(name, fn) and xdescribe.each`table`(name, fn)

Use describe.skip.each if you want to stop running a suite of data driven tests.

describe.skip.each is available with two 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 ran
});
});
test('will be ran', () => {
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 $b', ({a, b, expected}) => {
test('will not be ran', () => {
expect(a + b).toBe(expected); // will not be ran
});
});
test('will be ran', () => {
expect(1 / 0).toBe(Infinity);
});

test(name, fn, timeout)#

Also under the alias: 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. The third argument (optional) is timeout (in milliseconds) for specifying how long to wait before aborting. Note: The default timeout is 5 seconds.

Note: If a promise is returned from test, Jest will wait for the promise to resolve before letting the test complete. Jest will also wait if you provide an argument to the test function, usually called done. This could be handy when you want to test callbacks. See how to test async code here.

Por exemplo, digamos que fetchBeverageList() retorna uma promessa que é esperada resolver em uma lista que contém lemon nela. Você pode testar isso com:

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

Mesmo que a chamada para o test retornará imediatamente, o teste não concluirá até que a promessa também resolva.

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 of Arrays with the arguments that are passed into the test fn for each row.
    • Note 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]]
  • nome: String the title of the test block.
    • Generate unique test titles by positionally injecting parameters with printf formatting:
      • %p - pretty-format.
      • %s- String.
      • %d- Number.
      • %i - Integer.
      • %f - Floating point value.
      • %j - JSON.
      • %o - Object.
      • %# - Index of the test case.
      • %% - single percent sign ('%'). This does not consume an argument.
  • fn: Function the test to be ran, this is the function that will receive the parameters in each row as function arguments.
  • Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait for each row before aborting. Note: 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);
});

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

  • table: Tagged Template Literal
    • First row of variable name column headings separated with |
    • One or more subsequent rows of data supplied as template literal expressions using ${value} syntax.
  • nome: String the title of the test, use $variable to inject test data into the test title from the tagged template expressions.
    • To inject nested object values use you can supply a keyPath i.e. $variable.path.to.value
  • fn: Function the test to be ran, this is the function that will receive the test data object.
  • Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait for each row before aborting. Note: 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 $b', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});

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. Note: 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 ran', () => {
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 $b', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});
test('will not be ran', () => {
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 ran
});
test('will be ran', () => {
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 $b', ({a, b, expected}) => {
expect(a + b).toBe(expected); // will not be ran
});
test('will be ran', () => {
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.

Note: If you supply a test callback function then the test.todo will throw an error. If you have already implemented the test and it is broken and you do not want it to run, then use test.skip instead.

API#

  • name: String the title of the test plan.

Example:

const add = (a, b) => a + b;
test.todo('add should be associative');