1"use strict";(globalThis.webpackChunkjest_website||=[]).push([[7723],{23252(e,n,t){t.r(n),t.d(n,{assets:()=>d,contentTitle:()=>o,default:()=>x,frontMatter:()=>r,metadata:()=>s,toc:()=>h});const s=JSON.parse('{"id":"api","title":"Globals","description":"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\'.","source":"@site/../docs/GlobalAPI.md","sourceDirName":".","slug":"/api","permalink":"/docs/next/api","draft":false,"unlisted":false,"editUrl":"https://github.com/jestjs/jest/edit/main/website/../docs/GlobalAPI.md","tags":[],"version":"current","lastUpdatedBy":"John Vandenberg","lastUpdatedAt":1736922959000,"frontMatter":{"id":"api","title":"Globals"},"sidebar":"api","next":{"title":"Expect","permalink":"/docs/next/expect"}}');var i=t(62540),a=t(43023),c=t(9764),l=t(11038);const r={id:"api",title:"Globals"},o=void 0,d={},h=[...c.RM,{value:"Methods",id:"methods",level:2},{value:"Reference",id:"reference",level:2},{value:"<code>afterAll(fn, timeout)</code>",id:"afterallfn-timeout",level:3},{value:"<code>afterEach(fn, timeout)</code>",id:"aftereachfn-timeout",level:3},{value:"<code>beforeAll(fn, timeout)</code>",id:"beforeallfn-timeout",level:3},{value:"<code>beforeEach(fn, timeout)</code>",id:"beforeeachfn-timeout",level:3},{value:"<code>describe(name, fn)</code>",id:"describename-fn",level:3},{value:"<code>describe.each(table)(name, fn, timeout)</code>",id:"describeeachtablename-fn-timeout",level:3},{value:"1. <code>describe.each(table)(name, fn, timeout)</code>",id:"1-describeeachtablename-fn-timeout",level:4},{value:"2. <code>describe.each`table`(name, fn, timeout)</code>",id:"2-describeeachtablename-fn-timeout",level:4},{value:"<code>describe.only(name, fn)</code>",id:"describeonlyname-fn",level:3},{value:"<code>describe.only.each(table)(name, fn)</code>",id:"describeonlyeachtablename-fn",level:3},{value:"<code>describe.only.each(table)(name, fn)</code>",id:"describeonlyeachtablename-fn-1",level:4},{value:"<code>describe.only.each`table`(name, fn)</code>",id:"describeonlyeachtablename-fn-2",level:4},{value:"<code>describe.skip(name, fn)</code>",id:"describeskipname-fn",level:3},{value:"<code>describe.skip.each(table)(name, fn)</code>",id:"describeskipeachtablename-fn",level:3},{value:"<code>describe.skip.each(table)(name, fn)</code>",id:"describeskipeachtablename-fn-1",level:4},{value:"<code>describe.skip.each`table`(name, fn)</code>",id:"describeskipeachtablename-fn-2",level:4},{value:"<code>test(name, fn, timeout)</code>",id:"testname-fn-timeout",level:3},{value:"<code>test.concurrent(name, fn, timeout)</code>",id:"testconcurrentname-fn-timeout",level:3},{value:"<code>test.concurrent.each(table)(name, fn, timeout)</code>",id:"testconcurrenteachtablename-fn-timeout",level:3},{value:"1. <code>test.concurrent.each(table)(name, fn, timeout)</code>",id:"1-testconcurrenteachtablename-fn-timeout",level:4},{value:"2. <code>test.concurrent.each`table`(name, fn, timeout)</code>",id:"2-testconcurrenteachtablename-fn-timeout",level:4},{value:"<code>test.concurrent.only.each(table)(name, fn)</code>",id:"testconcurrentonlyeachtablename-fn",level:3},{value:"<code>test.concurrent.only.each(table)(name, fn)</code>",id:"testconcurrentonlyeachtablename-fn-1",level:4},{value:"<code>test.only.each`table`(name, fn)</code>",id:"testonlyeachtablename-fn",level:4},{value:"<code>test.concurrent.skip.each(table)(name, fn)</code>",id:"testconcurrentskipeachtablename-fn",level:3},{value:"<code>test.concurrent.skip.each(table)(name, fn)</code>",id:"testconcurrentskipeachtablename-fn-1",level:4},{value:"<code>test.concurrent.skip.each`table`(name, fn)</code>",id:"testconcurrentskipeachtablename-fn-2",level:4},{value:"<code>test.each(table)(name, fn, timeout)</code>",id:"testeachtablename-fn-timeout",level:3},{value:"1. <code>test.each(table)(name, fn, timeout)</code>",id:"1-testeachtablename-fn-timeout",level:4},{value:"2. <code>test.each`table`(name, fn, timeout)</code>
1",id:"2-testeachtablename-fn-timeout",level:4},{value:"<code>test.failing(name, fn, timeout)</code>",id:"testfailingname-fn-timeout",level:3},{value:"<code>test.failing.each(name, fn, timeout)</code>",id:"testfailingeachname-fn-timeout",level:3},{value:"<code>test.only.failing(name, fn, timeout)</code>",id:"testonlyfailingname-fn-timeout",level:3},{value:"<code>test.skip.failing(name, fn, timeout)</code>",id:"testskipfailingname-fn-timeout",level:3},{value:"<code>test.only(name, fn, timeout)</code>",id:"testonlyname-fn-timeout",level:3},{value:"<code>test.only.each(table)(name, fn)</code>",id:"testonlyeachtablename-fn-1",level:3},{value:"<code>test.only.each(table)(name, fn)</code>",id:"testonlyeachtablename-fn-2",level:4},{value:"<code>test.only.each`table`(name, fn)</code>",id:"testonlyeachtablename-fn-3",level:4},{value:"<code>test.skip(name, fn)</code>",id:"testskipname-fn",level:3},{value:"<code>test.skip.each(table)(name, fn)</code>",id:"testskipeachtablename-fn",level:3},{value:"<code>test.skip.each(table)(name, fn)</code>",id:"testskipeachtablename-fn-1",level:4},{value:"<code>test.skip.each`table`(name, fn)</code>",id:"testskipeachtablename-fn-2",level:4},{value:"<code>test.todo(name)</code>",id:"testtodoname",level:3},{value:"TypeScript Usage",id:"typescript-usage",level:2},...c.RM,{value:"<code>.each</code>",id:"each",level:3},{value:"Array of objects",id:"array-of-objects",level:4},{value:"Array of arrays",id:"array-of-arrays",level:4},{value:"Template literal",id:"template-literal",level:4}];function u(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",h4:"h4",hr:"hr",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,a.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(n.p,{children:["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 ",(0,i.jsx)(n.code,{children:"import {describe, expect, test} from '@jest/globals'"}),"."]}),"\n","\n",(0,i.jsx)(c.Ay,{}),"\n",(0,i.jsx)(n.h2,{id:"methods",children:"Methods"}),"\n","\n",(0,i.jsx)(l.A,{toc:h.slice(1)}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"reference",children:"Reference"}),"\n",(0,i.jsx)(n.h3,{id:"afterallfn-timeout",children:(0,i.jsx)(n.code,{children:"afterAll(fn, timeout)"})}),"\n",(0,i.jsx)(n.p,{children:"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."}),"\n",(0,i.jsxs)(n.p,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait before aborting. The default timeout is 5 seconds."]}),"\n",(0,i.jsx)(n.p,{children:"This is often useful if you want to clean up some global setup state that is shared across tests."}),"\n",(0,i.jsx)(n.p,{children:"For example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"const globalDatabase = makeGlobalDatabase();\n\nfunction cleanUpDatabase(db) {\n db.cleanUp();\n}\n\nafterAll(() =>
1 {\n cleanUpDatabase(globalDatabase);\n});\n\ntest('can find things', () => {\n return globalDatabase.find('thing', {}, results => {\n expect(results.length).toBeGreaterThan(0);\n });\n});\n\ntest('can insert a thing', () => {\n return globalDatabase.insert('thing', makeThing(), response => {\n expect(response.success).toBeTruthy();\n });\n});\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Here the ",(0,i.jsx)(n.code,{children:"afterAll"})," ensures that ",(0,i.jsx)(n.code,{children:"cleanUpDatabase"})," is called after all tests run."]}),"\n",(0,i.jsxs)(n.p,{children:["If ",(0,i.jsx)(n.code,{children:"afterAll"})," is inside a ",(0,i.jsx)(n.code,{children:"describe"})," block, it runs at the end of the describe block."]}),"\n",(0,i.jsxs)(n.p,{children:["If you want to run some cleanup after every test instead of after all tests, use ",(0,i.jsx)(n.code,{children:"afterEach"})," instead."]}),"\n",(0,i.jsx)(n.h3,{id:"aftereachfn-timeout",children:(0,i.jsx)(n.code,{children:"afterEach(fn, timeout)"})}),"\n",(0,i.jsx)(n.p,{children:"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."}),"\n",(0,i.jsxs)(n.p,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait before aborting. The default timeout is 5 seconds."]}),"\n",(0,i.jsx)(n.p,{children:"This is often useful if you want to clean up some temporary state that is created by each test."}),"\n",(0,i.jsx)(n.p,{children:"For example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"const globalDatabase = makeGlobalDatabase();\n\nfunction cleanUpDatabase(db) {\n db.cleanUp();\n}\n\nafterEach(() => {\n cleanUpDatabase(globalDatabase);\n});\n\ntest('can find things', () => {\n return globalDatabase.find('thing', {}, results => {\n expect(results.length).toBeGreaterThan(0);\n });\n});\n\ntest('can insert a thing', () => {\n return globalDatabase.insert('thing', makeThing(), response => {\n expect(response.success).toBeTruthy();\n });\n});\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Here the ",(0,i.jsx)(n.code,{children:"afterEach"})," ensures that ",(0,i.jsx)(n.code,{children:"cleanUpDatabase"})," is called after each test runs."]}),"\n",(0,i.jsxs)(n.p,{children:["If ",(0,i.jsx)(n.code,{children:"afterEach"})," is inside a ",(0,i.jsx)(n.code,{children:"describe"})," block, it only runs after the tests that are inside this describe block."]}),"\n",(0,i.jsxs)(n.p,{children:["If you want to run some cleanup just once, after all of the tests run, use ",(0,i.jsx)(n.code,{children:"afterAll"})," instead."]}),"\n",(0,i.jsx)(n.h3,{id:"beforeallfn-timeout",children:(0,i.jsx)(n.code,{children:"beforeAll(fn, timeout)"})}),"\n",(0,i.jsx)(n.p,{children:"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."}),"\n",(0,i.jsxs)(n.p,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait before aborting. The default timeout is 5 seconds."]}),"\n",(0,i.jsx)(n.p,{children:"This is often useful if you want to set up some global state that will be used by many tests."}),"\n",(0,i.jsx)(n.p,{children:"For example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"const globalDatabase = makeGlobalDatabase();\n\nbeforeAll(() =>
1 {\n // Clears the database and adds some testing data.\n // Jest will wait for this promise to resolve before running tests.\n return globalDatabase.clear().then(() => {\n return globalDatabase.insert({testData: 'foo'});\n });\n});\n\n// Since we only set up the database once in this example, it's important\n// that our tests don't modify it.\ntest('can find things', () => {\n return globalDatabase.find('thing', {}, results => {\n expect(results.length).toBeGreaterThan(0);\n });\n});\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Here the ",(0,i.jsx)(n.code,{children:"beforeAll"})," ensures that the database is set up before tests run. If setup was synchronous, you could do this without ",(0,i.jsx)(n.code,{children:"beforeAll"}),". The key is that Jest will wait for a promise to resolve, so you can have asynchronous setup as well."]}),"\n",(0,i.jsxs)(n.p,{children:["If ",(0,i.jsx)(n.code,{children:"beforeAll"})," is inside a ",(0,i.jsx)(n.code,{children:"describe"})," block, it runs at the beginning of the describe block."]}),"\n",(0,i.jsxs)(n.p,{children:["If you want to run something before every test instead of before any test runs, use ",(0,i.jsx)(n.code,{children:"beforeEach"})," instead."]}),"\n",(0,i.jsx)(n.h3,{id:"beforeeachfn-timeout",children:(0,i.jsx)(n.code,{children:"beforeEach(fn, timeout)"})}),"\n",(0,i.jsx)(n.p,{children:"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."}),"\n",(0,i.jsxs)(n.p,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait before aborting. The default timeout is 5 seconds."]}),"\n",(0,i.jsx)(n.p,{children:"This is often useful if you want to reset some global state that will be used by many tests."}),"\n",(0,i.jsx)(n.p,{children:"For example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"const globalDatabase = makeGlobalDatabase();\n\nbeforeEach(() => {\n // Clears the database and adds some testing data.\n // Jest will wait for this promise to resolve before running tests.\n return globalDatabase.clear().then(() => {\n return globalDatabase.insert({testData: 'foo'});\n });\n});\n\ntest('can find things', () => {\n return globalDatabase.find('thing', {}, results => {\n expect(results.length).toBeGreaterThan(0);\n });\n});\n\ntest('can insert a thing', () => {\n return globalDatabase.insert('thing', makeThing(), response => {\n expect(response.success).toBeTruthy();\n });\n});\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Here the ",(0,i.jsx)(n.code,{children:"beforeEach"})," ensures that the database is reset for each test."]}),"\n",(0,i.jsxs)(n.p,{children:["If ",(0,i.jsx)(n.code,{children:"beforeEach"})," is inside a ",(0,i.jsx)(n.code,{children:"describe"})," block, it runs for each test in the describe block."]}),"\n",(0,i.jsxs)(n.p,{children:["If you only need to run some setup code once, before any tests run, use ",(0,i.jsx)(n.code,{children:"beforeAll"})," instead."]}),"\n",(0,i.jsx)(n.h3,{id:"describename-fn",children:(0,i.jsx)(n.code,{children:"describe(name, fn)"})}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"describe(name, fn)"})," creates a block that groups together several related tests. For example, if you have a ",(0,i.jsx)(n.code,{children:"myBeverage"})," object that is supposed to be delicious but not sour, you could test it with:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"const myBeverage = {\n delicious: true,\n sour: false,\n};\n\ndescribe('my beverage', () => {\n test('is delicious', () => {\n expect(myBeverage.delicious).toBeTruthy();\n });\n\n test('is not sour', () => {\n expect(myBeverage.sour).toBeFalsy();\n });\n});\n"})}),"\n",(0,i.jsxs)(n.p,{children:["This isn't required - you can write the ",(0,i.jsx)(n.code,{children:"test"})," blocks directly at the top level. But this can be handy if you prefer your tests to be organized into groups."]}),"\n",(0,i.jsxs)(n.p,{children:["You can also nest ",(0,i.jsx)(n.code,{children:"describe"})," blocks if you have a hierarchy of tests:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"const binaryStringToNumber = binString => {\n if (!/^[01]+$/.test(binString)) {\n throw new CustomError('Not a binary number.');\n }\n\n return parseInt(binString, 2);\n};\n\ndescribe('binaryStringToNumber', () =>
1 {\n describe('given an invalid binary string', () => {\n test('composed of non-numbers throws CustomError', () => {\n expect(() => binaryStringToNumber('abc')).toThrow(CustomError);\n });\n\n test('with extra whitespace throws CustomError', () => {\n expect(() => binaryStringToNumber(' 100')).toThrow(CustomError);\n });\n });\n\n describe('given a valid binary string', () => {\n test('returns the correct number', () => {\n expect(binaryStringToNumber('100')).toBe(4);\n });\n });\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"describeeachtablename-fn-timeout",children:(0,i.jsx)(n.code,{children:"describe.each(table)(name, fn, timeout)"})}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"describe.each"})," if you keep duplicating the same test suites with different data. ",(0,i.jsx)(n.code,{children:"describe.each"})," allows you to write the test suite once and pass data in."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"describe.each"})," is available with two APIs:"]}),"\n",(0,i.jsxs)(n.h4,{id:"1-describeeachtablename-fn-timeout",children:["1. ",(0,i.jsx)(n.code,{children:"describe.each(table)(name, fn, timeout)"})]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"table"}),": ",(0,i.jsx)(n.code,{children:"Array"})," of Arrays with the arguments that are passed into the ",(0,i.jsx)(n.code,{children:"fn"})," for each row. If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. ",(0,i.jsx)(n.code,{children:"[1, 2, 3] -> [[1], [2], [3]]"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"name"}),": ",(0,i.jsx)(n.code,{children:"String"})," the title of the test suite."]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Generate unique test titles by positionally injecting parameters with ",(0,i.jsxs)(n.a,{href:"https://nodejs.org/api/util.html#util_util_format_format_args",children:[(0,i.jsx)(n.code,{children:"printf"})," formatting"]}),":","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%p"})," - ",(0,i.jsx)(n.a,{href:"https://www.npmjs.com/package/pretty-format",children:"pretty-format"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%s"}),"- String."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%d"}),"- Number."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%i"})," - Integer."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%f"})," - Floating point value."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%j"})," - JSON."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%o"})," - Object."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%#"})," - Index of the test case."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%$"})," - Number of the test case."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%%"})," - single percent sign ('%'). This does not consume an argument."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["Or generate unique test titles by injecting properties of test case object with ",(0,i.jsx)(n.code,{children:"$variable"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["To inject nested object values use you can supply a keyPath i.e. ",(0,i.jsx)(n.code,{children:"$variable.path.to.value"})," (only works for ",(0,i.jsx)(n.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty",children:'"own" properties'}),", e.g. ",(0,i.jsx)(n.code,{children:"$variable.constructor.name"})," wouldn't work)"]}),"\n",(0,i.jsxs)(n.li,{children:["You can use ",(0,i.jsx)(n.code,{children:"$#"})," to inject the index of the test case"]}),"\n",(0,i.jsxs)(n.li,{children:["You cannot use ",(0,i.jsx)(n.code,{children:"$variable"})," with the ",(0,i.jsx)(n.code,{children:"printf"})," formatting except for ",(0,i.jsx)(n.code,{children:"%%"})]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"fn"}),": ",(0,i.jsx)(n.code,{children:"Function"})," the suite of tests to be run, this is the function that will receive the parameters in each row as function arguments."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"Example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"describe.each([\n [1, 1, 2],\n [1, 2, 3],\n [2, 1, 3],\n])('.add(%i, %i)', (a, b, expected) =>
1 {\n test(`returns ${expected}`, () => {\n expect(a + b).toBe(expected);\n });\n\n test(`returned value not be greater than ${expected}`, () => {\n expect(a + b).not.toBeGreaterThan(expected);\n });\n\n test(`returned value not be less than ${expected}`, () => {\n expect(a + b).not.toBeLessThan(expected);\n });\n});\n"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"describe.each([\n {a: 1, b: 1, expected: 2},\n {a: 1, b: 2, expected: 3},\n {a: 2, b: 1, expected: 3},\n])('.add($a, $b)', ({a, b, expected}) => {\n test(`returns ${expected}`, () => {\n expect(a + b).toBe(expected);\n });\n\n test(`returned value not be greater than ${expected}`, () => {\n expect(a + b).not.toBeGreaterThan(expected);\n });\n\n test(`returned value not be less than ${expected}`, () => {\n expect(a + b).not.toBeLessThan(expected);\n });\n});\n"})}),"\n",(0,i.jsxs)(n.h4,{id:"2-describeeachtablename-fn-timeout",children:["2. ",(0,i.jsx)(n.code,{children:"describe.each`table`(name, fn, timeout)"})]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"table"}),": ",(0,i.jsx)(n.code,{children:"Tagged Template Literal"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["First row of variable name column headings separated with ",(0,i.jsx)(n.code,{children:"|"})]}),"\n",(0,i.jsxs)(n.li,{children:["One or more subsequent rows of data supplied as template literal expressions using ",(0,i.jsx)(n.code,{children:"${value}"})," syntax."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"name"}),": ",(0,i.jsx)(n.code,{children:"String"})," the title of the test suite, use ",(0,i.jsx)(n.code,{children:"$variable"})," to inject test data into the suite title from the tagged template expressions, and ",(0,i.jsx)(n.code,{children:"$#"})," for the index of the row.","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["To inject nested object values use you can supply a keyPath i.e. ",(0,i.jsx)(n.code,{children:"$variable.path.to.value"})," (only works for ",(0,i.jsx)(n.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty",children:'"own" properties'}),", e.g. ",(0,i.jsx)(n.code,{children:"$variable.constructor.name"})," wouldn't work)"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"fn"}),": ",(0,i.jsx)(n.code,{children:"Function"})," the suite of tests to be run, this is the function that will receive the test data object."]}),"\n",(0,i.jsxs)(n.li,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds."]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"Example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"describe.each`\n a | b | expected\n ${1} | ${1} | ${2}\n ${1} | ${2} | ${3}\n ${2} | ${1} | ${3}\n`('$a + $b', ({a, b, expected}) => {\n test(`returns ${expected}`, () => {\n expect(a + b).toBe(expected);\n });\n\n test(`returned value not be greater than ${expected}`, () => {\n expect(a + b).not.toBeGreaterThan(expected);\n });\n\n test(`returned value not be less than ${expected}`, () => {\n expect(a + b).not.toBeLessThan(expected);\n });\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"describeonlyname-fn",children:(0,i.jsx)(n.code,{children:"describe.only(name, fn)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"fdescribe(name, fn)"})]}),"\n",(0,i.jsxs)(n.p,{children:["You can use ",(0,i.jsx)(n.code,{children:"describe.only"})," if you want to run only one describe block:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"describe.only('my beverage', () => {\n test('is delicious', () => {\n expect(myBeverage.delicious).toBeTruthy();\n });\n\n test('is not sour', () => {\n expect(myBeverage.sour).toBeFalsy();\n });\n});\n\ndescribe('my other beverage', () => {\n // ... will be skipped\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"describeonlyeachtablename-fn",children:(0,i.jsx)(n.code,{children:"describe.only.each(table)(name, fn)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the aliases: ",(0,i.jsx)(n.code,{children:"fdescribe.each(table)(name, fn)"})," and ",(0,i.jsx)(n.code,{children:"fdescribe.each`table`(name, fn)"})]}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"describe.only.each"})," if you want to only run specific tests suites of data driven tests."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"describe.only.each"})," is available with two APIs:"]}),"\n",(0,i.jsx)(n.h4,{id:"describeonlyeachtablename-fn-1",children:(0,i.jsx)(n.code,{children:"describe.only.each(table)(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"describe.only.each([\n [1, 1, 2],\n [1, 2, 3],\n [2, 1, 3],\n])('.add(%i, %i)', (a, b, expected) =>
1 {\n test(`returns ${expected}`, () => {\n expect(a + b).toBe(expected);\n });\n});\n\ntest('will not be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h4,{id:"describeonlyeachtablename-fn-2",children:(0,i.jsx)(n.code,{children:"describe.only.each`table`(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"describe.only.each`\n a | b | expected\n ${1} | ${1} | ${2}\n ${1} | ${2} | ${3}\n ${2} | ${1} | ${3}\n`('returns $expected when $a is added to $b', ({a, b, expected}) => {\n test('passes', () => {\n expect(a + b).toBe(expected);\n });\n});\n\ntest('will not be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"describeskipname-fn",children:(0,i.jsx)(n.code,{children:"describe.skip(name, fn)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"xdescribe(name, fn)"})]}),"\n",(0,i.jsxs)(n.p,{children:["You can use ",(0,i.jsx)(n.code,{children:"describe.skip"})," if you do not want to run the tests of a particular ",(0,i.jsx)(n.code,{children:"describe"})," block:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"describe('my beverage', () => {\n test('is delicious', () => {\n expect(myBeverage.delicious).toBeTruthy();\n });\n\n test('is not sour', () => {\n expect(myBeverage.sour).toBeFalsy();\n });\n});\n\ndescribe.skip('my other beverage', () => {\n // ... will be skipped\n});\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Using ",(0,i.jsx)(n.code,{children:"describe.skip"})," is often a cleaner alternative to temporarily commenting out a chunk of tests. Beware that the ",(0,i.jsx)(n.code,{children:"describe"})," block will still run. If you have some setup that also should be skipped, do it in a ",(0,i.jsx)(n.code,{children:"beforeAll"})," or ",(0,i.jsx)(n.code,{children:"beforeEach"})," block."]}),"\n",(0,i.jsx)(n.h3,{id:"describeskipeachtablename-fn",children:(0,i.jsx)(n.code,{children:"describe.skip.each(table)(name, fn)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the aliases: ",(0,i.jsx)(n.code,{children:"xdescribe.each(table)(name, fn)"})," and ",(0,i.jsx)(n.code,{children:"xdescribe.each`table`(name, fn)"})]}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"describe.skip.each"})," if you want to stop running a suite of data driven tests."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"describe.skip.each"})," is available with two APIs:"]}),"\n",(0,i.jsx)(n.h4,{id:"describeskipeachtablename-fn-1",children:(0,i.jsx)(n.code,{children:"describe.skip.each(table)(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"describe.skip.each([\n [1, 1, 2],\n [1, 2, 3],\n [2, 1, 3],\n])('.add(%i, %i)', (a, b, expected) => {\n test(`returns ${expected}`, () => {\n expect(a + b).toBe(expected); // will not be run\n });\n});\n\ntest('will be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h4,{id:"describeskipeachtablename-fn-2",children:(0,i.jsx)(n.code,{children:"describe.skip.each`table`(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"describe.skip.each`\n a | b | expected\n ${1} | ${1} | ${2}\n ${1} | ${2} | ${3}\n ${2} | ${1} | ${3}\n`('returns $expected when $a is added to $b', ({a, b, expected}) => {\n test('will not be run', () => {\n expect(a + b).toBe(expected); // will not be run\n });\n});\n\ntest('will be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"testname-fn-timeout",children:(0,i.jsx)(n.code,{children:"test(name, fn, timeout)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"it(name, fn, timeout)"})]}),"\n",(0,i.jsxs)(n.p,{children:["All you need in a test file is the ",(0,i.jsx)(n.code,{children:"test"})," method which runs a test. For example, let's say there's a function ",(0,i.jsx)(n.code,{children:"inchesOfRain()"})," that should be zero. Your whole test could be:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test('did not rain', () => {\n expect(inchesOfRain()).toBe(0);\n});\n"})}),"\n",(0,i.jsxs)(n.p,{children:["The first argument is the test name; the second argument is a function that contains the expectations to test. The third argument (optional) is ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait before aborting. The default timeout is 5 seconds."]}),"\n",(0,i.jsxs)(n.p,{children:["If a ",(0,i.jsx)(n.strong,{children:"promise is returned"})," from ",(0,i.jsx)(n.code,{children:"test"}),", Jest will wait for the promise to resolve before letting the test complete. For example, let's say ",(0,i.jsx)(n.code,{children:"fetchBeverageList(
1)"})," returns a promise that is supposed to resolve to a list that has ",(0,i.jsx)(n.code,{children:"lemon"})," in it. You can test this with:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test('has lemon in it', () => {\n return fetchBeverageList().then(list => {\n expect(list).toContain('lemon');\n });\n});\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Even though the call to ",(0,i.jsx)(n.code,{children:"test"})," will return right away, the test doesn't complete until the promise resolves. For more details, see ",(0,i.jsx)(n.a,{href:"/docs/next/asynchronous",children:"Testing Asynchronous Code"})," page."]}),"\n",(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsxs)(n.p,{children:["Jest will also wait if you ",(0,i.jsx)(n.strong,{children:"provide an argument to the test function"}),", usually called ",(0,i.jsx)(n.code,{children:"done"}),". This could be handy when you want to test ",(0,i.jsx)(n.a,{href:"/docs/next/asynchronous#callbacks",children:"callbacks"}),"."]})}),"\n",(0,i.jsx)(n.h3,{id:"testconcurrentname-fn-timeout",children:(0,i.jsx)(n.code,{children:"test.concurrent(name, fn, timeout)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"it.concurrent(name, fn, timeout)"})]}),"\n",(0,i.jsx)(n.admonition,{type:"caution",children:(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"test.concurrent"})," is considered experimental - see ",(0,i.jsx)(n.a,{href:"https://github.com/jestjs/jest/labels/Area%3A%20Concurrent",children:"here"})," for details on missing features and other issues."]})}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"test.concurrent"})," if you want the test to run concurrently."]}),"\n",(0,i.jsxs)(n.p,{children:["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 ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait before aborting. The default timeout is 5 seconds."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.concurrent('addition of 2 numbers', async () => {\n expect(5 + 3).toBe(8);\n});\n\ntest.concurrent('subtraction 2 numbers', async () => {\n expect(5 - 3).toBe(2);\n});\n"})}),"\n",(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsxs)(n.p,{children:["Use the ",(0,i.jsx)(n.a,{href:"/docs/next/configuration#maxconcurrency-number",children:(0,i.jsx)(n.code,{children:"maxConcurrency"})})," configuration option to prevent Jest from executing more than the specified amount of tests at the same time."]})}),"\n",(0,i.jsx)(n.h3,{id:"testconcurrenteachtablename-fn-timeout",children:(0,i.jsx)(n.code,{children:"test.concurrent.each(table)(name, fn, timeout)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"it.concurrent.each(table)(name, fn, timeout)"})]}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"test.concurrent.each"})," if you keep duplicating the same test with different data. ",(0,i.jsx)(n.code,{children:"test.each"})," allows you to write the test once and pass data in, the tests are all run asynchronously."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"test.concurrent.each"})," is available with two APIs:"]}),"\n",(0,i.jsxs)(n.h4,{id:"1-testconcurrenteachtablename-fn-timeout",children:["1. ",(0,i.jsx)(n.code,{children:"test.concurrent.each(table)(name, fn, timeout)"})]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"table"}),": ",(0,i.jsx)(n.code,{children:"Array"})," of Arrays with the arguments that are passed into the test ",(0,i.jsx)(n.code,{children:"fn"})," for each row. If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. ",(0,i.jsx)(n.code,{children:"[1, 2, 3] -> [[1], [2], [3]]"})]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"name"}),": ",(0,i.jsx)(n.code,{children:"String"})," the title of the test block.","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Generate unique test titles by positionally injecting parameters with ",(0,i.jsxs)(n.a,{href:"https://nodejs.org/api/util.html#util_util_format_format_args",children:[(0,i.jsx)(n.code,{children:"printf"})," formatting"]}),":","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%p"})," - ",(0,i.jsx)(n.a,{href:"https://www.npmjs.com/package/pretty-format",children:"pretty-format"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%s"}),"- String."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%d"}),"- Number."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%i"})," - Integer."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%f"})," - Floating point value."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%j"})," - JSON."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%o"})," - Object."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%#"})," - Index of the test case."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%$"})," - Number of the test case."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%%"})," - single percent sign ('%'). This does not consume an argument."]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"fn"}),": ",(0,i.jsx)(n.code,{children:"Function"})," the test to be run, this is the function that will receive the parameters in each row as function arguments, ",(0,i.jsx)(n.strong,{children:"this will have to be an asynchronous function"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds."]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"Example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.concurrent.each([\n [1, 1, 2],\n [1, 2, 3],\n [2, 1, 3],\n])('.add(%i, %i)', async (a, b, expected) =>
1 {\n expect(a + b).toBe(expected);\n});\n"})}),"\n",(0,i.jsxs)(n.h4,{id:"2-testconcurrenteachtablename-fn-timeout",children:["2. ",(0,i.jsx)(n.code,{children:"test.concurrent.each`table`(name, fn, timeout)"})]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"table"}),": ",(0,i.jsx)(n.code,{children:"Tagged Template Literal"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["First row of variable name column headings separated with ",(0,i.jsx)(n.code,{children:"|"})]}),"\n",(0,i.jsxs)(n.li,{children:["One or more subsequent rows of data supplied as template literal expressions using ",(0,i.jsx)(n.code,{children:"${value}"})," syntax."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"name"}),": ",(0,i.jsx)(n.code,{children:"String"})," the title of the test, use ",(0,i.jsx)(n.code,{children:"$variable"})," to inject test data into the test title from the tagged template expressions.","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["To inject nested object values use you can supply a keyPath i.e. ",(0,i.jsx)(n.code,{children:"$variable.path.to.value"})," (only works for ",(0,i.jsx)(n.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty",children:'"own" properties'}),", e.g. ",(0,i.jsx)(n.code,{children:"$variable.constructor.name"})," wouldn't work)"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"fn"}),": ",(0,i.jsx)(n.code,{children:"Function"})," the test to be run, this is the function that will receive the test data object, ",(0,i.jsx)(n.strong,{children:"this will have to be an asynchronous function"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds."]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"Example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.concurrent.each`\n a | b | expected\n ${1} | ${1} | ${2}\n ${1} | ${2} | ${3}\n ${2} | ${1} | ${3}\n`('returns $expected when $a is added to $b', async ({a, b, expected}) => {\n expect(a + b).toBe(expected);\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"testconcurrentonlyeachtablename-fn",children:(0,i.jsx)(n.code,{children:"test.concurrent.only.each(table)(name, fn)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"it.concurrent.only.each(table)(name, fn)"})]}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"test.concurrent.only.each"})," if you want to only run specific tests with different test data concurrently."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"test.concurrent.only.each"})," is available with two APIs:"]}),"\n",(0,i.jsx)(n.h4,{id:"testconcurrentonlyeachtablename-fn-1",children:(0,i.jsx)(n.code,{children:"test.concurrent.only.each(table)(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.concurrent.only.each([\n [1, 1, 2],\n [1, 2, 3],\n [2, 1, 3],\n])('.add(%i, %i)', async (a, b, expected) => {\n expect(a + b).toBe(expected);\n});\n\ntest('will not be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h4,{id:"testonlyeachtablename-fn",children:(0,i.jsx)(n.code,{children:"test.only.each`table`(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.concurrent.only.each`\n a | b | expected\n ${1} | ${1} | ${2}\n ${1} | ${2} | ${3}\n ${2} | ${1} | ${3}\n`('returns $expected when $a is added to $b', async ({a, b, expected}) => {\n expect(a + b).toBe(expected);\n});\n\ntest('will not be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"testconcurrentskipeachtablename-fn",children:(0,i.jsx)(n.code,{children:"test.concurrent.skip.each(table)(name, fn)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"it.concurrent.skip.each(table)(name, fn)"})]}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"test.concurrent.skip.each"})," if you want to stop running a collection of asynchronous data driven tests."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"test.concurrent.skip.each"})," is available with two APIs:"]}),"\n",(0,i.jsx)(n.h4,{id:"testconcurrentskipeachtablename-fn-1",children:(0,i.jsx)(n.code,{children:"test.concurrent.skip.each(table)(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.concurrent.skip.each([\n [1, 1, 2],\n [1, 2, 3],\n [2, 1, 3],\n])('.add(%i, %i)', async (a, b, expected) =>
1 {\n expect(a + b).toBe(expected); // will not be run\n});\n\ntest('will be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h4,{id:"testconcurrentskipeachtablename-fn-2",children:(0,i.jsx)(n.code,{children:"test.concurrent.skip.each`table`(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.concurrent.skip.each`\n a | b | expected\n ${1} | ${1} | ${2}\n ${1} | ${2} | ${3}\n ${2} | ${1} | ${3}\n`('returns $expected when $a is added to $b', async ({a, b, expected}) => {\n expect(a + b).toBe(expected); // will not be run\n});\n\ntest('will be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"testeachtablename-fn-timeout",children:(0,i.jsx)(n.code,{children:"test.each(table)(name, fn, timeout)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"it.each(table)(name, fn)"})," and ",(0,i.jsx)(n.code,{children:"it.each`table`(name, fn)"})]}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"test.each"})," if you keep duplicating the same test with different data. ",(0,i.jsx)(n.code,{children:"test.each"})," allows you to write the test once and pass data in."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"test.each"})," is available with two APIs:"]}),"\n",(0,i.jsxs)(n.h4,{id:"1-testeachtablename-fn-timeout",children:["1. ",(0,i.jsx)(n.code,{children:"test.each(table)(name, fn, timeout)"})]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"table"}),": ",(0,i.jsx)(n.code,{children:"Array"})," of Arrays with the arguments that are passed into the test ",(0,i.jsx)(n.code,{children:"fn"})," for each row. If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. ",(0,i.jsx)(n.code,{children:"[1, 2, 3] -> [[1], [2], [3]]"})]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"name"}),": ",(0,i.jsx)(n.code,{children:"String"})," the title of the test block.","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Generate unique test titles by positionally injecting parameters with ",(0,i.jsxs)(n.a,{href:"https://nodejs.org/api/util.html#util_util_format_format_args",children:[(0,i.jsx)(n.code,{children:"printf"})," formatting"]}),":","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%p"})," - ",(0,i.jsx)(n.a,{href:"https://www.npmjs.com/package/pretty-format",children:"pretty-format"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%s"}),"- String."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%d"}),"- Number."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%i"})," - Integer."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%f"})," - Floating point value."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%j"})," - JSON."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%o"})," - Object."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%#"})," - Index of the test case."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%$"})," - Number of the test case."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"%%"})," - single percent sign ('%'). This does not consume an argument."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["Or generate unique test titles by injecting properties of test case object with ",(0,i.jsx)(n.code,{children:"$variable"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["To inject nested object values use you can supply a keyPath i.e. ",(0,i.jsx)(n.code,{children:"$variable.path.to.value"})," (only works for ",(0,i.jsx)(n.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty",children:'"own" properties'}),", e.g. ",(0,i.jsx)(n.code,{children:"$variable.constructor.name"})," wouldn't work)"]}),"\n",(0,i.jsxs)(n.li,{children:["You can use ",(0,i.jsx)(n.code,{children:"$#"})," to inject the index of the test case"]}),"\n",(0,i.jsxs)(n.li,{children:["You cannot use ",(0,i.jsx)(n.code,{children:"$variable"})," with the ",(0,i.jsx)(n.code,{children:"printf"})," formatting except for ",(0,i.jsx)(n.code,{children:"%%"})]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"fn"}),": ",(0,i.jsx)(n.code,{children:"Function"})," the test to be run, this is the function that will receive the parameters in each row as function arguments."]}),"\n",(0,i.jsxs)(n.li,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds."]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"Example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.each([\n [1, 1, 2],\n [1, 2, 3],\n [2, 1, 3],\n])('.add(%i, %i)', (a, b, expected) =>
1 {\n expect(a + b).toBe(expected);\n});\n"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.each([\n {a: 1, b: 1, expected: 2},\n {a: 1, b: 2, expected: 3},\n {a: 2, b: 1, expected: 3},\n])('.add($a, $b)', ({a, b, expected}) => {\n expect(a + b).toBe(expected);\n});\n"})}),"\n",(0,i.jsxs)(n.h4,{id:"2-testeachtablename-fn-timeout",children:["2. ",(0,i.jsx)(n.code,{children:"test.each`table`(name, fn, timeout)"})]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"table"}),": ",(0,i.jsx)(n.code,{children:"Tagged Template Literal"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["First row of variable name column headings separated with ",(0,i.jsx)(n.code,{children:"|"})]}),"\n",(0,i.jsxs)(n.li,{children:["One or more subsequent rows of data supplied as template literal expressions using ",(0,i.jsx)(n.code,{children:"${value}"})," syntax."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"name"}),": ",(0,i.jsx)(n.code,{children:"String"})," the title of the test, use ",(0,i.jsx)(n.code,{children:"$variable"})," to inject test data into the test title from the tagged template expressions.","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["To inject nested object values use you can supply a keyPath i.e. ",(0,i.jsx)(n.code,{children:"$variable.path.to.value"})," (only works for ",(0,i.jsx)(n.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty",children:'"own" properties'}),", e.g. ",(0,i.jsx)(n.code,{children:"$variable.constructor.name"})," wouldn't work)"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"fn"}),": ",(0,i.jsx)(n.code,{children:"Function"})," the test to be run, this is the function that will receive the test data object."]}),"\n",(0,i.jsxs)(n.li,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds."]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"Example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.each`\n a | b | expected\n ${1} | ${1} | ${2}\n ${1} | ${2} | ${3}\n ${2} | ${1} | ${3}\n`('returns $expected when $a is added to $b', ({a, b, expected}) => {\n expect(a + b).toBe(expected);\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"testfailingname-fn-timeout",children:(0,i.jsx)(n.code,{children:"test.failing(name, fn, timeout)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"it.failing(name, fn, timeout)"})]}),"\n",(0,i.jsx)(n.admonition,{type:"note",children:(0,i.jsxs)(n.p,{children:["This is only available with the default ",(0,i.jsx)(n.a,{href:"https://github.com/jestjs/jest/tree/main/packages/jest-circus",children:"jest-circus"})," runner."]})}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"test.failing"})," when you are writing a test and expecting it to fail. These tests will behave the other way normal tests do. If ",(0,i.jsx)(n.code,{children:"failing"})," test will throw any errors then it will pass. If it does not throw it will fail."]}),"\n",(0,i.jsxs)(n.admonition,{type:"tip",children:[(0,i.jsxs)(n.p,{children:["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. The
1n you can just remove the ",(0,i.jsx)(n.code,{children:"failing"})," modifier to make them pass."]}),(0,i.jsx)(n.p,{children:"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."})]}),"\n",(0,i.jsx)(n.p,{children:"Example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.failing('it is not equal', () => {\n expect(5).toBe(6); // this test will pass\n});\n\ntest.failing('it is equal', () => {\n expect(10).toBe(10); // this test will fail\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"testfailingeachname-fn-timeout",children:(0,i.jsx)(n.code,{children:"test.failing.each(name, fn, timeout)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"it.failing.each(table)(name, fn)"})," and ",(0,i.jsx)(n.code,{children:"it.failing.each`table`(name, fn)"})]}),"\n",(0,i.jsx)(n.admonition,{type:"note",children:(0,i.jsxs)(n.p,{children:["This is only available with the default ",(0,i.jsx)(n.a,{href:"https://github.com/jestjs/jest/tree/main/packages/jest-circus",children:"jest-circus"})," runner."]})}),"\n",(0,i.jsxs)(n.p,{children:["You can also run multiple tests at once by adding ",(0,i.jsx)(n.code,{children:"each"})," after ",(0,i.jsx)(n.code,{children:"failing"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"Example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.failing.each([\n {a: 1, b: 1, expected: 2},\n {a: 1, b: 2, expected: 3},\n {a: 2, b: 1, expected: 3},\n])('.add($a, $b)', ({a, b, expected}) => {\n expect(a + b).toBe(expected);\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"testonlyfailingname-fn-timeout",children:(0,i.jsx)(n.code,{children:"test.only.failing(name, fn, timeout)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the aliases: ",(0,i.jsx)(n.code,{children:"it.only.failing(name, fn, timeout)"}),", ",(0,i.jsx)(n.code,{children:"fit.failing(name, fn, timeout)"})]}),"\n",(0,i.jsx)(n.admonition,{type:"note",children:(0,i.jsxs)(n.p,{children:["This is only available with the default ",(0,i.jsx)(n.a,{href:"https://github.com/jestjs/jest/tree/main/packages/jest-circus",children:"jest-circus"})," runner."]})}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"test.only.failing"})," if you want to only run a specific failing test."]}),"\n",(0,i.jsx)(n.h3,{id:"testskipfailingname-fn-timeout",children:(0,i.jsx)(n.code,{children:"test.skip.failing(name, fn, timeout)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the aliases: ",(0,i.jsx)(n.code,{children:"it.skip.failing(name, fn, timeout)"}),", ",(0,i.jsx)(n.code,{children:"xit.failing(name, fn, timeout)"}),", ",(0,i.jsx)(n.code,{children:"xtest.failing(name, fn, timeout)"})]}),"\n",(0,i.jsx)(n.admonition,{type:"note",children:(0,i.jsxs)(n.p,{children:["This is only available with the default ",(0,i.jsx)(n.a,{href:"https://github.com/jestjs/jest/tree/main/packages/jest-circus",children:"jest-circus"})," runner."]})}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"test.skip.failing"})," if you want to skip running a specific failing test."]}),"\n",(0,i.jsx)(n.h3,{id:"testonlyname-fn-timeout",children:(0,i.jsx)(n.code,{children:"test.only(name, fn, timeout)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the aliases: ",(0,i.jsx)(n.code,{children:"it.only(name, fn, timeout)"}),", and ",(0,i.jsx)(n.code,{children:"fit(name, fn, timeout)"})]}),"\n",(0,i.jsxs)(n.p,{children:["When you are debugging a large test file, you will often only want to run a subset of tests. You can use ",(0,i.jsx)(n.code,{children:".only"})," to specify which tests are the only ones you want to run in that test file."]}),"\n",(0,i.jsxs)(n.p,{children:["Optionally, you can provide a ",(0,i.jsx)(n.code,{children:"timeout"})," (in milliseconds) for specifying how long to wait before aborting. The default timeout is 5 seconds."]}),"\n",(0,i.jsx)(n.p,{children:"For example, let's say you had these tests:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.only('it is raining', () => {\n expect(inchesOfRain()).toBeGreaterThan(0);\n});\n\ntest('it is not snowing', () => {\n expect(inchesOfSnow()).toBe(0);\n});\n"})}),"\n",(0,i.jsxs)(n.p,{children:['Only the "it is raining" test will run in that test file, since it is run with ',(0,i.jsx)(n.code,{children:"test.only"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["Usually you wouldn't check code using ",(0,i.jsx)(n.code,{children:"test.only"})," into source control - you would use it for debugging, and remove it once you have fixed the broken tests."]}),"\n",(0,i.jsx)(n.h3,{id:"testonlyeachtablename-fn-1",children:(0,i.jsx)(n.code,{children:"test.only.each(table)(name, fn)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the aliases: ",(0,i.jsx)(n.code,{children:"it.only.each(table)(name, fn)"}),", ",(0,i.jsx)(n.code,{children:"fit.each(table)(name, fn)"}),", ",(0,i.jsx)(n.code,{children:"it.only.each`table`(name, fn)"})," and ",(0,i.jsx)(n.code,{children:"fit.each`table`(name, fn)"})]}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"test.only.each"})," if you want to only run specific tests with different test data."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"test.only.each"})," is available with two APIs:"]}),"\n",(0,i.jsx)(n.h4,{id:"testonlyeachtablename-fn-2",children:(0,i.jsx)(n.code,{children:"test.only.each(table)(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.only.each([\n [1, 1, 2],\n [1, 2, 3],\n [2, 1, 3],\n])('.add(%i, %i)', (a, b, expected) =>
1 {\n expect(a + b).toBe(expected);\n});\n\ntest('will not be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h4,{id:"testonlyeachtablename-fn-3",children:(0,i.jsx)(n.code,{children:"test.only.each`table`(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.only.each`\n a | b | expected\n ${1} | ${1} | ${2}\n ${1} | ${2} | ${3}\n ${2} | ${1} | ${3}\n`('returns $expected when $a is added to $b', ({a, b, expected}) => {\n expect(a + b).toBe(expected);\n});\n\ntest('will not be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"testskipname-fn",children:(0,i.jsx)(n.code,{children:"test.skip(name, fn)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the aliases: ",(0,i.jsx)(n.code,{children:"it.skip(name, fn)"}),", ",(0,i.jsx)(n.code,{children:"xit(name, fn)"}),", and ",(0,i.jsx)(n.code,{children:"xtest(name, fn)"})]}),"\n",(0,i.jsxs)(n.p,{children:["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 ",(0,i.jsx)(n.code,{children:"test.skip"})," to specify some tests to skip."]}),"\n",(0,i.jsx)(n.p,{children:"For example, let's say you had these tests:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test('it is raining', () => {\n expect(inchesOfRain()).toBeGreaterThan(0);\n});\n\ntest.skip('it is not snowing', () => {\n expect(inchesOfSnow()).toBe(0);\n});\n"})}),"\n",(0,i.jsxs)(n.p,{children:['Only the "it is raining" test will run, since the other test is run with ',(0,i.jsx)(n.code,{children:"test.skip"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["You could comment the test out, but it's often a bit nicer to use ",(0,i.jsx)(n.code,{children:"test.skip"})," because it will maintain indentation and syntax highlighting."]}),"\n",(0,i.jsx)(n.h3,{id:"testskipeachtablename-fn",children:(0,i.jsx)(n.code,{children:"test.skip.each(table)(name, fn)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the aliases: ",(0,i.jsx)(n.code,{children:"it.skip.each(table)(name, fn)"}),", ",(0,i.jsx)(n.code,{children:"xit.each(table)(name, fn)"}),", ",(0,i.jsx)(n.code,{children:"xtest.each(table)(name, fn)"}),", ",(0,i.jsx)(n.code,{children:"it.skip.each`table`(name, fn)"}),", ",(0,i.jsx)(n.code,{children:"xit.each`table`(name, fn)"})," and ",(0,i.jsx)(n.code,{children:"xtest.each`table`(name, fn)"})]}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"test.skip.each"})," if you want to stop running a collection of data driven tests."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"test.skip.each"})," is available with two APIs:"]}),"\n",(0,i.jsx)(n.h4,{id:"testskipeachtablename-fn-1",children:(0,i.jsx)(n.code,{children:"test.skip.each(table)(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.skip.each([\n [1, 1, 2],\n [1, 2, 3],\n [2, 1, 3],\n])('.add(%i, %i)', (a, b, expected) => {\n expect(a + b).toBe(expected); // will not be run\n});\n\ntest('will be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h4,{id:"testskipeachtablename-fn-2",children:(0,i.jsx)(n.code,{children:"test.skip.each`table`(name, fn)"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"test.skip.each`\n a | b | expected\n ${1} | ${1} | ${2}\n ${1} | ${2} | ${3}\n ${2} | ${1} | ${3}\n`('returns $expected when $a is added to $b', ({a, b, expected}) => {\n expect(a + b).toBe(expected); // will not be run\n});\n\ntest('will be run', () => {\n expect(1 / 0).toBe(Infinity);\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"testtodoname",children:(0,i.jsx)(n.code,{children:"test.todo(name)"})}),"\n",(0,i.jsxs)(n.p,{children:["Also under the alias: ",(0,i.jsx)(n.code,{children:"it.todo(name)"})]}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"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."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"const add = (a, b) => a + b;\n\ntest.todo('add should be associative');\n"})}),"\n",(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"test.todo"})," will throw an error if you pass it a test callback function. Use ",(0,i.jsx)(n.a,{href:"#testskipname-fn",children:(0,i.jsx)(n.code,{children:"test.
1skip"})})," instead, if you already implemented the test, but do not want it to run."]})}),"\n",(0,i.jsx)(n.h2,{id:"typescript-usage",children:"TypeScript Usage"}),"\n",(0,i.jsx)(c.Ay,{}),"\n",(0,i.jsx)(n.h3,{id:"each",children:(0,i.jsx)(n.code,{children:".each"})}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:".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 ",(0,i.jsx)(n.code,{children:"describe"})," or ",(0,i.jsx)(n.code,{children:"test"})," callback functions. Let's take a look at each of them."]}),"\n",(0,i.jsx)(n.admonition,{type:"note",children:(0,i.jsxs)(n.p,{children:["For simplicity ",(0,i.jsx)(n.code,{children:"test.each"})," is picked for the examples, but the type inference is identical in all cases where ",(0,i.jsx)(n.code,{children:".each"})," modifier can be used: ",(0,i.jsx)(n.code,{children:"describe.each"}),", ",(0,i.jsx)(n.code,{children:"test.concurrent.only.each"}),", ",(0,i.jsx)(n.code,{children:"test.skip.each"}),", etc."]})}),"\n",(0,i.jsx)(n.h4,{id:"array-of-objects",children:"Array of objects"}),"\n",(0,i.jsxs)(n.p,{children:["The array of objects API is most verbose, but it makes the type inference a painless task. A ",(0,i.jsx)(n.code,{children:"table"})," can be inlined:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {test} from '@jest/globals';\n\ntest.each([\n {name: 'a', path: 'path/to/a', count: 1, write: true},\n {name: 'b', path: 'path/to/b', count: 3},\n])('inline table', ({name, path, count, write}) => {\n // arguments are typed as expected, e.g. `write: boolean | undefined`\n});\n"})}),"\n",(0,i.jsx)(n.p,{children:"Or declared separately as a variable:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {test} from '@jest/globals';\n\nconst table = [\n {a: 1, b: 2, expected: 'three', extra: true},\n {a: 3, b: 4, expected: 'seven', extra: false},\n {a: 5, b: 6, expected: 'eleven'},\n];\n\ntest.each(table)('table as a variable', ({a, b, expected, extra}) => {\n // again everything is typed as expected, e.g. `extra: boolean | undefined`\n});\n"})}),"\n",(0,i.jsx)(n.h4,{id:"array-of-arrays",children:"Array of arrays"}),"\n",(0,i.jsx)(n.p,{children:"The array of arrays style will work smoothly with inlined tables:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {test} from '@jest/globals';\n\ntest.each([\n [1, 2, 'three', true],\n [3, 4, 'seven', false],\n [5, 6, 'eleven'],\n])('inline table example', (a, b, expected, extra) => {\n // arguments are typed as expected, e.g. `extra: boolean | undefined`\n});\n"})}),"\n",(0,i.jsx)(n.p,{children:"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):"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {test} from '@jest/globals';\n\nconst table: Array<[number, number, string, boolean?]> = [\n [1, 2, 'three', true],\n [3, 4, 'seven', false],\n [5, 6, 'eleven'],\n];\n\ntest.each(table)('table as a variable example', (a, b, expected, extra) => {\n // without the annotation types are incorrect, e.g. `a: number | string | boolean`\n});\n"})}),"\n",(0,i.jsx)(n.h4,{id:"template-literal",children:"Template literal"}),"\n",(0,i.jsx)(n.p,{children:"If all input values are of the same type, the template literal API will type the arguments correctly:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {test} from '@jest/globals';\n\ntest.each`\n a | b | expected\n ${1} | ${2} | ${3}\n ${3} | ${4} | ${7}\n ${5} | ${6} | ${11}\n`('template literal example same type', ({a, b, expected}) => {\n // all arguments are of type `number` because all inputs (a, b, expected) are of type `number`\n});\n"})}),"\n",(0,i.jsx)(n.p,{children:"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):"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {test} from '@jest/globals';\n\ntest.each`\n a | b | expected\n ${1} | ${2} | ${'three'}\n ${3} | ${4} | ${'seven'}\n ${5} | ${6} | ${'eleven'}\n`('template literal example different types', ({a, b, expected}) => {\n // all arguments are of type `number | string` because some inputs (a, b) are of type `number` and some others (expected) are of type `string`\n});\n"})}),"\n",(0,i.jsx)(n.p,{children:"Otherwise, if you want each argument to have the right type, you have to explicitly provide the generic type argument:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {test} from '@jest/globals';\n\ntest.each<{a: number; b: number; expected: string; extra?: boolean}>`\n a | b | expected | extra\n ${1} | ${2} | ${'three'} | ${true}\n ${3} | ${4} | ${'seven'} | ${false}\n ${5} | ${6} | ${'eleven'}\n`('template literal example', ({a, b, expected, extra}) => {\n // all arguments are typed as expected, e.g. `a: number`, `expected: string`, `extra: boolean | undefined`\n});\n"})}),"\n",(0,i.jsxs)(n.admonition,{type:"caution",children:[(0,i.jsx)(n.p,{children:"Keep in mind the variables inside the template literal are not type checked, so you have to ensure that their types are correct."}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {test} from '@jest/globals';\n\ntest.each<{a: number; expected: string}>`\n a | expected\n ${1} | ${'one'}\n ${'will not raise TS error'} | ${'two'}\n ${3} | ${'three'}\n`('template literal with wrongly typed input', ({a, expected}) => {\n // all arguments are typed as stated in the generic: `a: number`, `expected: string`\n // WARNING: `a` is of type `number` but will be a string in the 2nd test case.\n});\n"})})]})]})}function x(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(u,{...e})}):u(e)}},9764(e,n,t){t.d(n,{Ay:()=>c});var s=t(62540),i=t(43023);function a(e){const n={a:"a",admonition:"admonition",code:"code",p:"p",pre:"pre",...(0,i.R)(),...e.components};return(0,s.jsxs)(n.admonition,{type:"info",children:[(0,s.jsx)(n.p,{children:"The TypeScript examples from this page will only work as documented if you explicitly import Jest APIs:"}),(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-ts",children:"import {expect, jest, test} from '@jest/globals';\n"})}),(0,s.jsxs)(n.p,{children:["Consult the ",(0,s.jsx)(n.a,{href:"/docs/next/getting-started#using-typescript",children:"Getting Started"})," guide for details on how to setup Jest with TypeScript."]})]})}function c(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(a,{...e})}):a(e)}t.d(n,["RM",0,[]])},11038(e,n,t){t.d(n,{A:()=>c});t(63696);var s=t(15397);const i="tableOfContentsInline_pY9K";var a=t(62540);function c({toc:e,minHeadingLevel:n,maxHeadingLevel:t}){return(0,a.jsx)("div",{className:i,children:(0,a.jsx)(s.A,{toc:e,minHeadingLevel:n,maxHeadingLevel:t,className:"table-of-contents",linkClassName:null})})}},15397(e,n,t){t.d(n,{A:()=>j});var s=t(63696),i=t(27412);function a(e){const n=e.map(e=>
1({...e,parentIndex:-1,children:[]})),t=Array(7).fill(-1);n.forEach((e,n)=>{const s=t.slice(2,e.level);e.parentIndex=Math.max(...s),t[e.level]=n});const s=[];return n.forEach(e=>{const{parentIndex:t,...i}=e;t>=0?n[t].children.push(i):s.push(i)}),s}function c({toc:e,minHeadingLevel:n,maxHeadingLevel:t}){return e.flatMap(e=>{const s=c({toc:e.children,minHeadingLevel:n,maxHeadingLevel:t});return function(e){return e.level>=n&&e.level<=t}(e)?[{...e,children:s}]:s})}function l(e){const n=e.getBoundingClientRect();return n.top===n.bottom?l(e.parentNode):n}function r(e,{anchorTopOffset:n}){const t=e.find(e=>l(e).top>=n);if(t){return function(e){return e.top>0&&e.bottom<window.innerHeight/2}(l(t))?t:e[e.indexOf(t)-1]??null}return e[e.length-1]??null}function o(){const e=(0,s.useRef)(0),{navbar:{hideOnScroll:n}}=(0,i.p)();return(0,s.useEffect)(()=>{e.current=n?0:document.querySelector(".navbar").clientHeight},[n]),e}function d(e){const n=(0,s.useRef)(void 0),t=o();(0,s.useEffect)(()=>{if(!e)return()=>{};const{linkClassName:s,linkActiveClassName:i,minHeadingLevel:a,maxHeadingLevel:c}=e;function l(){const e=function(e){return Array.from(document.getElementsByClassName(e))}(s),l=function({minHeadingLevel:e,maxHeadingLevel:n}){const t=[];for(let s=e;s<=n;s+=1)t.push(`h${s}.anchor`);return Array.from(document.querySelectorAll(t.join()))}({minHeadingLevel:a,maxHeadingLevel:c}),o=r(l,{anchorTopOffset:t.current}),d=e.find(e=>o&&o.id===function(e){return decodeURIComponent(e.href.substring(e.href.indexOf("#")+1))}(e));e.forEach(e=>{!function(e,t){t?(n.current&&n.current!==e&&n.current.classList.remove(i),e.classList.add(i),n.current=e):e.classList.remove(i)}(e,e===d)})}return document.addEventListener("scroll",l),document.addEventListener("resize",l),l(),()=>{document.removeEventListener("scroll",l),document.removeEventListener("resize",l)}},[e,t])}var h=t(45968),u=t(62540);function x({toc:e,className:n,linkClassName:t,isChild:s}){return e.length?(0,u.jsx)("ul",{className:s?void 0:n,children:e.map(e=>(0,u.jsxs)("li",{children:[(0,u.jsx)(h.A,{to:`#${e.id}`,className:t??void 0,dangerouslySetInnerHTML:{__html:e.value}}),(0,u.jsx)(x,{isChild:!0,toc:e.children,className:n,linkClassName:t})]},e.id))}):null}const p=s.memo(x);function j({toc:e,className:n="table-of-contents table-of-contents__left-border",linkClassName:t="table-of-contents__link",linkActiveClassName:l,minHeadingLevel:r,maxHeadingLevel:o,...h}){const x=(0,i.p)(),j=r??x.tableOfContents.minHeadingLevel,f=o??x.tableOfContents.maxHeadingLevel,m=function({toc:e,minHeadingLevel:n,maxHeadingLevel:t}){return(0,s.useMemo)(()=>c({toc:a(e),minHeadingLevel:n,maxHeadingLevel:t}),[e,n,t])}({toc:e,minHeadingLevel:j,maxHeadingLevel:f});return d((0,s.useMemo)(()=>{if(t&&l)return{linkClassName:t,linkActiveClassName:l,minHeadingLevel:j,maxHeadingLevel:f}},[t,l,j,f])),(0,u.jsx)(p,{toc:m,className:n,linkClassName:t,...h})}},43023(e,n,t){t.d(n,{R:()=>c,x:()=>l});var s=t(63696);const i={},a=s.createContext(i);function c(e){const n=s.useContext(a);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:c(e.components),s.createElement(a.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.