Skip to content
Logo

Test identity

Every test, and every beforeAll and afterAll, has an identity. Integrations receive it in frame and in every provider, and derive per-test state from it.

type Identity = {
  kind: "test" | "suite";
  path: string[];
  name: string;
  row: number | undefined;
};
fieldfor a testfor beforeAll / afterAll
kind"test""suite"
paththe enclosing describe namesthe enclosing describe names
namethe test's name""
rowthe .each row index, from 0, or undefinedundefined
describe("users", () => {
  describe("signup", () => {
    it("rejects a short password", ({ … }) => {
      // { kind: "test", path: ["users", "signup"], name: "rejects a short password", row: undefined }
    });
  });
});

It's the path, not the file

Identity is fixed when a test is declared. It doesn't depend on which file the test is in, which other tests ran, or in what order. .only, name filters, sharding, retries, and .concurrent don't change it.

It's also the same on every runner. Some runners call a nested describe callback right away, and others wait until the enclosing one returns, and the path comes out the same either way.

Same path, same identity

Two tests with the same describe names and the same name have the same identity, even in different files. That usually happens when a shared helper registers the same tests from several files. Each test still behaves the same on every run, so nothing breaks, but integrations give both the same per-test state. Give them different names.

kind keeps a test named "" apart from its suite. A beforeAll and an afterAll in the same describe share one identity on purpose.

describe.each needs a placeholder

An it.each row is in identity.row, so two rows with the same title still differ. A describe.each row reaches the identity only through the suite's name, so give that name a placeholder from the row:

describe.each(cases)("case $name", ({ it, row }) => { … }); // a path per row
describe.each(cases)("case", ({ it, row }) => { … }); // one path for every row

Without one, the tests in every row share a path, and integrations treat them as the same tests. See .each.

The runner's own describe drops out

framework.describe is the unwrapped runner, so harness doesn't see it. A wrapped it inside one gets the path without that name:

framework.describe("users", () => {
  it("signs up", () => {}); // path: [], not ["users"]
});

Always group with the wrapped describe. Use framework only for what harness doesn't wrap.

An async describe callback loses its path in a similar way after its first await. Harness throws rather than let that happen. See Async describe.