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;
};| field | for a test | for beforeAll / afterAll |
|---|---|---|
kind | "test" | "suite" |
path | the enclosing describe names | the enclosing describe names |
name | the test's name | "" |
row | the .each row index, from 0, or undefined | undefined |
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 rowWithout 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.
