| Method | Description |
|---|---|
| afterAll(fn, timeout) | Runs a function after all the tests in this file have completed. If the function returns a promise or is a generator, Jest waits for that promise to resolve before continuing. Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before aborting. Note: The default timeout is 5 seconds. This is often useful if you want to clean up some global setup state that is shared across tests. |
| afterEach(fn, timeout) | Runs a function after each one of the tests in this file completes. If the function returns a promise or is a generator, Jest waits for that promise to resolve before continuing. Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before aborting. Note: The default timeout is 5 seconds. This is often useful if you want to clean up some temporary state that is created by each test. |
| beforeAll(fn, timeout) | Runs a function before any of the tests in this file run. If the function returns a promise or is a generator, Jest waits for that promise to resolve before running tests. Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before aborting. Note: The default timeout is 5 seconds. This is often useful if you want to set up some global state that will be used by many tests. |
| beforeEach(fn, timeout) | Runs a function before each of the tests in this file runs. If the function returns a promise or is a generator, Jest waits for that promise to resolve before running the test. Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before aborting. Note: The default timeout is 5 seconds. This is often useful if you want to reset some global state that will be used by many tests. |
| describe(name, fn) | describe(name, fn) creates a block that groups together several related tests. For example, if you have a myBeverage object that is supposed to be delicious but not sour, you could test it with: |
| describe.each(table)(name, fn, timeout) |
Use describe.each if you keep duplicating the same test suites with different data. describe.each allows you to write the test suite once and pass data in.
describe.each is available with two APIs 1. 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]] name: String the title of the test suite. Generate unique test titles by positionally injecting parameters with printf formatting. 2. describe.each`table`(name, fn, timeout) full doc |
| describe.only(name, fn) | Also under the alias: fdescribe(name, fn) You can use describe.only if you want to run only one describe block: |
| 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: full doc |
| describe.skip(name, fn) | Also under the alias: xdescribe(name, fn) You can use describe.skip if you do not want to run a particular describe block: |
| 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: full doc |
| test(name, fn, timeout) |
Also under the alias: it(name, fn, timeout)
All you need in a test file is the test method which runs a test. For example, let's say there's a function inchesOfRain() that should be zero. Your whole test could be:
The first argument is the test name; the second argument is a function that contains the expectations to test. 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. |
| test.concurrent(name, fn, timeout) |
Also under the alias: it.concurrent(name, fn, timeout)
Use test.concurrent if you want the test to run concurrently.
The first argument is the test name; the second argument is an asynchronous function that contains the expectations to test. The third argument (optional) is timeout (in milliseconds) for specifying how long to wait before aborting. Note: The default timeout is 5 seconds. |
| test.concurrent.each(table)(name, fn, timeout) |
Also under the alias: it.concurrent.each(table)(name, fn, timeout)
Use test.concurrent.each if you keep duplicating the same test with different data. test.each allows you to write the test once and pass data in, the tests are all run asynchronously.
test.concurrent.each is available with two APIs: 1. test.concurrent.each(table)(name, fn, timeout) 2. test.concurrent.each`table`(name, fn, timeout) full doc |
| test.concurrent.only.each(table)(name, fn) |
Also under the alias: 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. full doc |
| 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. full doc |
| 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) 2. test.each`table`(name, fn, timeout) full doc |
| 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. Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before aborting. Note: The default timeout is 5 seconds. |
| 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: full doc |
| test.skip(name, fn) | Also under the aliases: it.skip(name, fn), xit(name, fn), and xtest(name, fn) When you are maintaining a large codebase, you may sometimes find a test that is temporarily broken for some reason. 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. |
| 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: full doc |
| 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. |
expect(value)
The expect function is used every time you want to test a value. You will rarely call expect by itself. Instead, you will use expect along with a "matcher" function to assert something about value.
It's easier to understand this with an example. Let's say you have a method bestLaCroixFlavor() which is supposed to return the string 'grapefruit'. Here's how you would test that:
test('the best flavor is grapefruit', () => {
expect(bestLaCroixFlavor()).toBe('grapefruit');
});In this case, toBe is the matcher function. There are a lot of different matcher functions, documented below, to help you test different things.
The argument to expect should be the value that your code produces, and any argument to the matcher should be the correct value. If you mix them up, your tests will still work, but the error messages on failing tests will look strange.
If you know how to test something, .not lets you test its opposite. For example, this code tests that the best La Croix flavor is not coconut:
test('the best flavor is not coconut', () => {
expect(bestLaCroixFlavor()).not.toBe('coconut');
});Use resolves to unwrap the value of a fulfilled promise so any other matcher can be chained. If the promise is rejected the assertion fails.
For example, this code tests that the promise resolves and that the resulting value is 'lemon':
test('resolves to lemon', () => {
// make sure to add a return statement
return expect(Promise.resolve('lemon')).resolves.toBe('lemon');
});Use .rejects to unwrap the reason of a rejected promise so any other matcher can be chained. If the promise is fulfilled the assertion fails.
For example, this code tests that the promise rejects with reason 'octopus':
test('rejects to octopus', () => {
// make sure to add a return statement
return expect(Promise.reject(new Error('octopus'))).rejects.toThrow(
'octopus',
);
});| Method | Description |
|---|---|
| expect.extend(matchers) | You can use expect.extend to add your own matchers to Jest. For example, let's say that you're testing a number utility library and you're frequently asserting that numbers appear within particular ranges of other numbers. You could abstract that into a toBeWithinRange matcher: |
| expect.anything() | matches anything but null or undefined. You can use it inside toEqual or toBeCalledWith instead of a literal value. For example, if you want to check that a mock function is called with a non-null argument: |
| expect.any(constructor) | expect.any(constructor) matches anything that was created with the given constructor. You can use it inside toEqual or toBeCalledWith instead of a literal value. For example, if you want to check that a mock function is called with a number: |
| expect.arrayContaining(array) |
matches a received array which contains all of the elements in the expected array. That is, the expected array is a subset of the received array. Therefore, it matches a received array which contains elements that are not in the expected array.
You can use it instead of a literal value:
- in toEqual or toBeCalledWith - to match a property in objectContaining or toMatchObject expect.not.arrayContaining(array) matches a received array which does not contain all of the elements in the expected array. That is, the expected array is not a subset of the received array. |
| expect.assertions(number) | verifies that a certain number of assertions are called during a test. This is often useful when testing asynchronous code, in order to make sure that assertions in a callback actually got called. For example, let's say that we have a function doAsync that receives two callbacks callback1 and callback2, it will asynchronously call both of them in an unknown order. We can test this with: |
| expect.hasAssertions() | verifies that at least one assertion is called during a test. This is often useful when testing asynchronous code, in order to make sure that assertions in a callback actually got called. For example, let's say that we have a few functions that all deal with state. prepareState calls a callback with a state object, validateState runs on that state object, and waitOnState returns a promise that waits until all prepareState callbacks complete. We can test this with: |
| expect.objectContaining(object) |
matches any received object that recursively matches the expected properties. That is, the expected object is a subset of the received object. Therefore, it matches a received object which contains properties that are present in the expected object.
Instead of literal property values in the expected object, you can use matchers, expect.anything(), and so on.
expect.not.objectContaining(object) matches any received object that does not recursively match the expected properties. That is, the expected object is not a subset of the received object. Therefore, it matches a received object which contains properties that are not in the expected object. |
| expect.stringContaining(string) |
matches the received value if it is a string that contains the exact expected string.
expect.not.stringContaining(string) matches the received value if it is not a string or if it is a string that does not contain the exact expected string. |
| expect.stringMatching(string | regexp) |
matches the received value if it is a string that matches the expected string or regular expression.
You can use it instead of a literal value:
-in toEqual or toBeCalledWith - to match an element in arrayContaining - to match a property in objectContaining or toMatchObject expect.not.stringMatching(string | regexp) matches the received value if it is not a string or if it is a string that does not match the expected string or regular expression. |
| expect.addSnapshotSerializer(serializer) |
You can call expect.addSnapshotSerializer to add a module that formats application-specific data structures.
For an individual test file, an added module precedes any modules from snapshotSerializers configuration, which precede the default snapshot serializers for built-in JavaScript types and for React elements. The last module added is the first module tested.
full doc |
| .toBe(value) |
Use .toBe to compare primitive values or to check referential identity of object instances. It calls Object.is to compare values, which is even better for testing than === strict equality operator.
Don't use .toBe with floating-point numbers. For example, due to rounding, in JavaScript 0.2 + 0.1 is not strictly equal to 0.3. If you have floating point numbers, try .toBeCloseTo instead. Although the .toBe matcher checks referential identity, it reports a deep comparison of values if the assertion fails. If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the expect function. For example, to assert whether or not elements are the same instance: rewrite expect(received).toBe(expected) as expect(Object.is(received, expected)).toBe(true) rewrite expect(received).not.toBe(expected) as expect(Object.is(received, expected)).toBe(false) |
| .toHaveBeenCalled() | Also under the alias: .toBeCalled() Use .toHaveBeenCalled to ensure that a mock function got called. |
| .toHaveBeenCalledTimes(number) | Also under the alias: .toBeCalledTimes(number) Use .toHaveBeenCalledTimes to ensure that a mock function got called exact number of times. |
| .toHaveBeenCalledWith(arg1, arg2, ...) | Also under the alias: .toBeCalledWith() Use .toHaveBeenCalledWith to ensure that a mock function was called with specific arguments. |
| .toHaveBeenLastCalledWith(arg1, arg2, ...) | Also under the alias: .lastCalledWith(arg1, arg2, ...) If you have a mock function, you can use .toHaveBeenLastCalledWith to test what arguments it was last called with. |
| .toHaveBeenNthCalledWith(nthCall, arg1, arg2, ....) | Also under the alias: .nthCalledWith(nthCall, arg1, arg2, ...) If you have a mock function, you can use .toHaveBeenNthCalledWith to test what arguments it was nth called with |
| .toHaveReturned() | Also under the alias: .toReturn() If you have a mock function, you can use .toHaveReturned to test that the mock function successfully returned (i.e., did not throw an error) at least one time. |
| .toHaveReturnedTimes(number) | lso under the alias: .toReturnTimes(number) Use .toHaveReturnedTimes to ensure that a mock function returned successfully (i.e., did not throw an error) an exact number of times. Any calls to the mock function that throw an error are not counted toward the number of times the function returned. |
| .toHaveReturnedWith(value) | Also under the alias: .toReturnWith(value) Use .toHaveReturnedWith to ensure that a mock function returned a specific value. |
| .toHaveLastReturnedWith(value) | Also under the alias: .lastReturnedWith(value) Use .toHaveLastReturnedWith to test the specific value that a mock function last returned. If the last call to the mock function threw an error, then this matcher will fail no matter what value you provided as the expected return value. |
| .toHaveNthReturnedWith(nthCall, value) | Also under the alias: .nthReturnedWith(nthCall, value) Use .toHaveNthReturnedWith to test the specific value that a mock function returned for the nth call. If the nth call to the mock function threw an error, then this matcher will fail no matter what value you provided as the expected return value. |
| .toHaveLength(number) | Use .toHaveLength to check that an object has a .length property and it is set to a certain numeric value. This is especially useful for checking arrays or strings size. |
| .toHaveProperty(keyPath, value?) | Use .toHaveProperty to check if property at provided reference keyPath exists for an object. For checking deeply nested properties in an object you may use dot notation or an array containing the keyPath for deep references. You can provide an optional value argument to compare the received property value (recursively for all properties of object instances, also known as deep equality, like the toEqual matcher). |
| .toBeCloseTo(number, numDigits?) |
Use toBeCloseTo to compare floating point numbers for approximate equality.
The optional numDigits argument limits the number of digits to check after the decimal point. For the default value 2, the test criterion is Math.abs(expected - received) < 0.005 (that is, 10 ** -2 / 2).
Intuitive equality comparisons often fail, because arithmetic on decimal (base 10) values often have rounding errors in limited precision binary (base 2) representation
* Because floating point errors are the problem that toBeCloseTo solves, it does not support big integer values. |
| .toBeDefined() | Use .toBeDefined to check that a variable is not undefined. For example, if you want to check that a function fetchNewFlavorIdea() returns something, you can write: |
| .toBeFalsy() | Use .toBeFalsy when you don't care what a value is and you want to ensure a value is false in a boolean context. In JavaScript, there are six falsy values: false, 0, '', null, undefined, and NaN. Everything else is truthy. |
| .toBeGreaterThan(number | bigint) | Use toBeGreaterThan to compare received > expected for number or big integer values. |
| .toBeGreaterThanOrEqual(number | bigint) | Use toBeGreaterThanOrEqual to compare received >= expected for number or big integer values. |
| .toBeLessThan(number | bigint) | Use toBeLessThan to compare received < expected for number or big integer values |
| .toBeLessThanOrEqual(number | bigint) | Use toBeLessThanOrEqual to compare received <= expected for number or big integer values |
| .toBeInstanceOf(Class) | Use .toBeInstanceOf(Class) to check that an object is an instance of a class |
| .toBeNull() | .toBeNull() is the same as .toBe(null) but the error messages are a bit nicer. So use .toBeNull() when you want to check that something is null. |
| .toBeTruthy() | Use .toBeTruthy when you don't care what a value is and you want to ensure a value is true in a boolean context |
| .toBeUndefined() | Use .toBeUndefined to check that a variable is undefined. For example, if you want to check that a function bestDrinkForFlavor(flavor) returns undefined for the 'octopus' flavor, because there is no good octopus-flavored drink: |
| .toBeNaN() | Use .toBeNaN when checking a value is NaN |
| .toContain(item) | Use .toContain when you want to check that an item is in an array. For testing the items in the array, this uses ===, a strict equality check. .toContain can also check whether a string is a substring of another string. |
| .toContainEqual(item) | Use .toContainEqual when you want to check that an item with a specific structure and values is contained in an array. For testing the items in the array, this matcher recursively checks the equality of all fields, rather than checking for object identity. |
| .toEqual(value) |
Use .toEqual to compare recursively all properties of object instances (also known as "deep" equality). It calls Object.is to compare primitive values, which is even better for testing than === strict equality operator.
Note: .toEqual won't perform a deep equality check for two errors. Only the message property of an Error is considered for equality. It is recommended to use the .toThrow matcher for testing against errors. |
| .toMatch(regexpOrString) | Use .toMatch to check that a string matches a regular expression. |
| .toMatchObject(object) |
Use .toMatchObject to check that a JavaScript object matches a subset of the properties of an object. It will match received objects with properties that are not in the expected object.
You can also pass an array of objects, in which case the method will return true only if each object in the received array matches (in the toMatchObject sense described above) the corresponding object in the expected array. This is useful if you want to check that two arrays match in their number of elements, as opposed to arrayContaining, which allows for extra elements in the received array. |
| .toMatchSnapshot(propertyMatchers?, hint?) |
This ensures that a value matches the most recent snapshot. Check out the Snapshot Testing guide for more information.
You can provide an optional propertyMatchers object argument, which has asymmetric matchers as values of a subset of expected properties, if the received value will be an object instance. It is like toMatchObject with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties. You can provide an optional hint string argument that is appended to the test name. Although Jest always appends a number at the end of a snapshot name, short descriptive hints might be more useful than numbers to differentiate multiple snapshots in a single it or test block. Jest sorts snapshots by name in the corresponding .snap file. |
| .toMatchInlineSnapshot(propertyMatchers?, inlineSnapshot) |
Ensures that a value matches the most recent snapshot.
You can provide an optional propertyMatchers object argument, which has asymmetric matchers as values of a subset of expected properties, if the received value will be an object instance. It is like toMatchObject with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties. Jest adds the inlineSnapshot string argument to the matcher in the test file (instead of an external .snap file) the first time that the test runs. Check out the section on Inline Snapshots for more info. |
| .toStrictEqual(value) |
Use .toStrictEqual to test that objects have the same types as well as structure.
Differences from .toEqual:
|
| .toThrow(error?) |
Also under the alias: .toThrowError(error?)
Use .toThrow to test that a function throws when it is calle
Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail. You can provide an optional argument to test that a specific error is thrown:
|
| .toThrowErrorMatchingSnapshot(hint?) | Use .toThrowErrorMatchingSnapshot to test that a function throws an error matching the most recent snapshot when it is called. You can provide an optional hint string argument that is appended to the test name. Although Jest always appends a number at the end of a snapshot name, short descriptive hints might be more useful than numbers to differentiate multiple snapshots in a single it or test block. Jest sorts snapshots by name in the corresponding .snap file. |
| .toThrowErrorMatchingInlineSnapshot(inlineSnapshot) | Use .toThrowErrorMatchingInlineSnapshot to test that a function throws an error matching the most recent snapshot when it is called. Jest adds the inlineSnapshot string argument to the matcher in the test file (instead of an external .snap file) the first time that the test runs |
Mock functions are also known as "spies", because they let you spy on the behavior of a function that is called indirectly by some other code, rather than only testing the output. You can create a mock function with jest.fn(). If no implementation is given, the mock function will return undefined when invoked.
| Prop/Method | Description |
|---|---|
| mockFn.getMockName() | Returns the mock name string set by calling mockFn.mockName(value). |
| mockFn.mock.calls | An array containing the call arguments of all calls that have been made to this mock function. Each item in the array is an array of arguments that were passed during the call. |
| mockFn.mock.results |
An array containing the results of all calls that have been made to this mock function. Each entry in this array is an object containing a type property, and a value property. type will be one of the following:
|
| mockFn.mock.instances | An array that contains all the object instances that have been instantiated from this mock function using new. |
| mockFn.mockClear() |
Resets all information stored in the mockFn.mock.calls and mockFn.mock.instances arrays.
Often this is useful when you want to clean up a mock's usage data between two assertions.
Beware that mockClear will replace mockFn.mock, not just mockFn.mock.calls and mockFn.mock.instances. You should, therefore, avoid assigning mockFn.mock to other variables, temporary or not, to make sure you don't access stale data. The clearMocks configuration option is available to clear mocks automatically between tests. |
| mockFn.mockReset() |
Does everything that mockFn.mockClear() does, and also removes any mocked return values or implementations.
This is useful when you want to completely reset a mock back to its initial state. (Note that resetting a spy will result in a function with no return value).
Beware that mockReset will replace mockFn.mock, not just mockFn.mock.calls and mockFn.mock.instances. You should, therefore, avoid assigning mockFn.mock to other variables, temporary or not, to make sure you don't access stale data. |
| mockFn.mockRestore() |
Does everything that mockFn.mockReset() does, and also restores the original (non-mocked) implementation.
This is useful when you want to mock functions in certain test cases and restore the original implementation in others.
Beware that mockFn.mockRestore only works when the mock was created with jest.spyOn. Thus you have to take care of restoration yourself when manually assigning jest.fn(). The restoreMocks configuration option is available to restore mocks automatically between tests. |
| mockFn.mockImplementation(fn) |
Accepts a function that should be used as the implementation of the mock. The mock itself will still record all calls that go into and instances that come from itself – the only difference is that the implementation will also be executed when the mock is called.
Note: jest.fn(implementation) is a shorthand for jest.fn().mockImplementation(implementation). |
| mockFn.mockImplementationOnce(fn) |
Accepts a function that will be used as an implementation of the mock for one call to the mocked function. Can be chained so that multiple function calls produce different results.
When the mocked function runs out of implementations defined with mockImplementationOnce, it will execute the default implementation set with jest.fn(() => defaultValue) or .mockImplementation(() => defaultValue) if they were called: |
| mockFn.mockName(value) | Accepts a string to use in test result output in place of "jest.fn()" to indicate which mock function is being referenced. |
| mockFn.mockReturnThis() |
Syntactic sugar function for:
jest.fn(function () { return this; }); |
| mockFn.mockReturnValue(value) | Accepts a value that will be returned whenever the mock function is called. |
| mockFn.mockReturnValueOnce(value) | Accepts a value that will be returned for one call to the mock function. Can be chained so that successive calls to the mock function return different values. When there are no more mockReturnValueOnce values to use, calls will return a value specified by mockReturnValue. |
| mockFn.mockResolvedValue(value) |
Syntactic sugar function for:
jest.fn().mockImplementation(() => Promise.resolve(value)); |
| mockFn.mockResolvedValueOnce(value) |
Syntactic sugar function for:
jest.fn().mockImplementationOnce(() => Promise.resolve(value)); |
| mockFn.mockRejectedValue(value) |
Syntactic sugar function for:
jest.fn().mockImplementation(() => Promise.reject(value)); |
| mockFn.mockRejectedValueOnce(value) |
Syntactic sugar function for:
jest.fn().mockImplementationOnce(() => Promise.reject(value)); |
The jest object is automatically in scope within every test file. The methods in the jest object help create mocks and let you control Jest's overall behavior. It can also be imported explicitly by via import {jest} from '@jest/globals'.
| Method | Description |
|---|---|
| jest.disableAutomock() | Disables automatic mocking in the module loader. Returns the jest object for chaining. |
| jest.enableAutomock() | Enables automatic mocking in the module loader. Returns the jest object for chaining. |
| jest.createMockFromModule(moduleName) |
Also under the alias: .genMockFromModule(moduleName)
Given the name of a module, use the automatic mocking system to generate a mocked version of the module for you.
full doc |
| jest.mock(moduleName, factory, options) |
Mocks a module with an auto-mocked version when it is being required. factory and options are optional
The second argument can be used to specify an explicit module factory that is being run instead of using Jest's automocking feature: The third argument can be used to create virtual mocks – mocks of modules that don't exist anywhere in the system Returns the jest object for chaining. |
| jest.unmock(moduleName) |
Indicates that the module system should never return a mocked version of the specified module from require() (e.g. that it should always return the real module).
The most common use of this API is for specifying the module a given test intends to be testing (and thus doesn't want automatically mocked).
Returns the jest object for chaining. |
| jest.doMock(moduleName, factory, options) |
When using babel-jest, calls to mock will automatically be hoisted to the top of the code block. Use this method if you want to explicitly avoid this behavior.
Returns the jest object for chaining. |
| jest.dontMock(moduleName) |
When using babel-jest, calls to unmock will automatically be hoisted to the top of the code block. Use this method if you want to explicitly avoid this behavior.
Returns the jest object for chaining. |
| jest.setMock(moduleName, moduleExports) |
Explicitly supplies the mock object that the module system should return for the specified module.
On occasion, there are times where the automatically generated mock the module system would normally provide you isn't adequate enough for your testing needs. Normally under those circumstances you should write a manual mock that is more adequate for the module in question. However, on extremely rare occasions, even a manual mock isn't suitable for your purposes and you need to build the mock yourself inside your test. Note It is recommended to use jest.mock() instead. The jest.mock API's second argument is a module factory instead of the expected exported module object. Returns the jest object for chaining. |
| jest.requireActual(moduleName) | Returns the actual module instead of a mock, bypassing all checks on whether the module should receive a mock implementation or not. |
| jest.requireMock(moduleName) | Returns a mock module instead of the actual module, bypassing all checks on whether the module should be required normally or not. |
| jest.resetModules() |
Resets the module registry - the cache of all required modules. This is useful to isolate modules where local state might conflict between tests.
Returns the jest object for chaining. |
| jest.isolateModules(fn) | jest.isolateModules(fn) goes a step further than jest.resetModules() and creates a sandbox registry for the modules that are loaded inside the callback function. This is useful to isolate specific modules for every test so that local module state doesn't conflict between tests. |
| jest.fn(implementation) | Returns a new, unused mock function. Optionally takes a mock implementation. |
| jest.isMockFunction(fn) | Determines if the given function is a mocked function. |
| jest.spyOn(object, methodName) |
Creates a mock function similar to jest.fn but also tracks calls to object[methodName]. Returns a Jest mock function.
Note: By default, jest.spyOn also calls the spied method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use jest.spyOn(object, methodName).mockImplementation(() => customImplementation) or object[methodName] = jest.fn(() => customImplementation); |
| jest.spyOn(object, methodName, accessType?) | Since Jest 22.1.0+, the jest.spyOn method takes an optional third argument of accessType that can be either 'get' or 'set', which proves to be useful when you want to spy on a getter or a setter, respectively. |
| jest.clearAllMocks() |
Clears the mock.calls and mock.instances properties of all mocks. Equivalent to calling .mockClear() on every mocked function.
Returns the jest object for chaining. |
| jest.resetAllMocks() |
Resets the state of all mocks. Equivalent to calling .mockReset() on every mocked function.
Returns the jest object for chaining. |
| jest.restoreAllMocks() | Restores all mocks back to their original value. Equivalent to calling .mockRestore() on every mocked function. Beware that jest.restoreAllMocks() only works when the mock was created with jest.spyOn; other mocks will require you to manually restore them. |
| jest.useFakeTimers(implementation?: 'modern' | 'legacy') |
Instructs Jest to use fake versions of the standard timer functions (setTimeout, setInterval, clearTimeout, clearInterval, nextTick, setImmediate and clearImmediate).
If you pass 'modern' as an argument, @sinonjs/fake-timers will be used as implementation instead of Jest's own fake timers. This also mocks additional timers like Date. 'modern' will be the default behavior in Jest 27. Returns the jest object for chaining. |
| jest.useRealTimers() |
Instructs Jest to use the real versions of the standard timer functions.
Returns the jest object for chaining. |
| jest.runAllTicks() |
Exhausts the micro-task queue (usually interfaced in node via process.nextTick).
When this API is called, all pending micro-tasks that have been queued via process.nextTick will be executed. Additionally, if those micro-tasks themselves schedule new micro-tasks, those will be continually exhausted until there are no more micro-tasks remaining in the queue. |
| jest.runAllTimers() |
Exhausts both the macro-task queue (i.e., all tasks queued by setTimeout(), setInterval(), and setImmediate()) and the micro-task queue (usually interfaced in node via process.nextTick).
When this API is called, all pending macro-tasks and micro-tasks will be executed. If those tasks themselves schedule new tasks, those will be continually exhausted until there are no more tasks remaining in the queue. This is often useful for synchronously executing setTimeouts during a test in order to synchronously assert about some behavior that would only happen after the setTimeout() or setInterval() callbacks executed. See the Timer mocks doc for more information. |
| jest.runAllImmediates() |
Exhausts all tasks queued by setImmediate().
Note: This function is not available when using modern fake timers implementation |
| jest.advanceTimersByTime(msToRun) |
Also under the alias: .runTimersToTime()
Executes only the macro task queue (i.e. all tasks queued by setTimeout() or setInterval() and setImmediate()). When this API is called, all timers are advanced by msToRun milliseconds. All pending "macro-tasks" that have been queued via setTimeout() or setInterval(), and would be executed within this time frame will be executed. Additionally, if those macro-tasks schedule new macro-tasks that would be executed within the same time frame, those will be executed until there are no more macro-tasks remaining in the queue, that should be run within msToRun milliseconds. |
| jest.runOnlyPendingTimers() |
Executes only the macro-tasks that are currently pending (i.e., only the tasks that have been queued by setTimeout() or setInterval() up to this point). If any of the currently pending macro-tasks schedule new macro-tasks, those new tasks will not be executed by this call.
This is useful for scenarios such as one where the module being tested schedules a setTimeout() whose callback schedules another setTimeout() recursively (meaning the scheduling never stops). In these scenarios, it's useful to be able to run forward in time by a single step at a time. |
| jest.advanceTimersToNextTimer(steps) | Advances all timers by the needed milliseconds so that only the next timeouts/intervals will run. Optionally, you can provide steps, so it will run steps amount of next timeouts/intervals. |
| jest.clearAllTimers() | Removes any pending timers from the timer system. This means, if any timers have been scheduled (but have not yet executed), they will be cleared and will never have the opportunity to execute in the future. |
| jest.getTimerCount() | Returns the number of fake timers still left to run. |
| jest.setSystemTime(now?: number | Date) |
Set the current system time used by fake timers. Simulates a user changing the system clock while your program is running. It affects the current time but it does not in itself cause e.g. timers to fire; they will fire exactly as they would have done without the call to jest.setSystemTime().
Note: This function is only available when using modern fake timers implementation |
| jest.getRealSystemTime() |
When mocking time, Date.now() will also be mocked. If you for some reason need access to the real current time, you can invoke this function.
Note: This function is only available when using modern fake timers implementation |
| jest.setTimeout(timeout) |
Set the default timeout interval for tests and before/after hooks in milliseconds. This only affects the test file from which this function is called.
Note: The default timeout interval is 5 seconds if this method is not called. Note: If you want to set the timeout for all test files, a good place to do this is in setupFilesAfterEnv |
| jest.retryTimes() |
Runs failed tests n-times until they pass or until the max number of retries is exhausted. This only works with jest-circus!
Returns the jest object for chaining. |