Writing tests

Tests live beside the code they cover, in each package's tests/ directory. Every suite in the default gate reports zero skipped, and a guard keeps it that way.

The contract

A test earns its place by catching a real regression and surviving unrelated edits.

Two artifacts that cannot import each other - Maestro flow files and their inventory, strip-marker regions and the CLI registry - may be compared by a test. List it in CROSS_ARTIFACT_CHECKS (packages/e2e-support/src/test-contract-debt.ts) with a one-line reason.

Conventions

• Build fixtures with typed factory helpers using Partial<T> from a package's exported types; never re-declare types by hand.
• Put temp paths under os.tmpdir(); never hard-code /tmp.
• Build a case's premise instead of assuming it: a file that must exist, an env var, a configured host. Prefer a synthetic fixture over your own tree, and register conditionally when the premise genuinely cannot exist.

No skips - register conditionally

it.skip, it.skipIf, describe.skipIf, runIf, fixme, todo and testInfo.skip are banned in both runners. A test that does not apply to your build is not registered.

// Wrong - the summary reports a skip, and every reader has to chase what it meant.
describe.skipIf(config.payment.provider !== "stripe")("stripe webhooks", () => { /* … */ });

// Right - the block exists only in a build that has the feature.
if (config.payment.provider === "stripe") {
	describe("stripe webhooks", () => { /* … */ });
}

Keep the inverse case wherever one exists. Nest both arms inside one describe - the shared ESLint preset's test/no-identical-title rejects two top-level describes with the same name:

describe("organizations", () => {
	if (config.tenancy.multiTenant) {
		it("invites a member", () => { /* … */ });
	} else {
		it("ships no organization surface", () => { /* … */ });
	}
});

Premise tests

A file whose every block is conditional registers one test in the other branch, asserting the config fact the file keys on. Both runners fail a file that registers nothing.

} else {
	it("this build ships no stripe provider", () => {
		expect(config.payment.provider).not.toBe("stripe");
	});
}

The guard

Two suites in packages/e2e-support/tests/ parse every test file with the TypeScript compiler API and run inside pnpm test, so they cover your tests as well as the shipped ones.

Opt-in suites

Each prints one not run: <item> — <why> line instead of a skip, and exits 0 when it finds nothing to run. An opt-in gate that finds nothing is a report, not a failure.