From 54eb92ab1481009e390856169719209b28498dca Mon Sep 17 00:00:00 2001 From: Hong Minhee Date: Wed, 27 May 2026 19:26:38 +0900 Subject: [PATCH] Update test harness guidance to prefer node:test Deno, Node.js, and Bun all support node:test and node:assert/strict natively, so there is no longer a need to use @fedify/fixture's test() wrapper in most packages. Update AGENTS.md, CONTRIBUTING.md, and the create-integration-package skill to reflect this: - Default guidance: use node:test + node:assert/strict directly. - Exception: @fedify/fedify and @fedify/vocab must keep using @fedify/fixture's test() because their Cloudflare Workers harness relies on the testDefinitions registry that fixture populates. - @fedify/fixture helpers (mockDocumentLoader, TestSpanExporter, etc.) remain available for any *.test.ts file regardless of test runner. Assisted-by: Claude Code:claude-sonnet-4-6 --- .../create-integration-package/SKILL.md | 20 ++++--- AGENTS.md | 30 ++++++---- CONTRIBUTING.md | 55 +++++++++++++++---- 3 files changed, 78 insertions(+), 27 deletions(-) diff --git a/.agents/skills/create-integration-package/SKILL.md b/.agents/skills/create-integration-package/SKILL.md index 8fc57ddb1..03d7e68df 100644 --- a/.agents/skills/create-integration-package/SKILL.md +++ b/.agents/skills/create-integration-package/SKILL.md @@ -190,20 +190,26 @@ later, but write unit tests as well if possible. Name test files with the #### Test runner -You can import the `test` function from `@fedify/fixture` for runtime-agnostic -tests that work across Deno, Node.js, and Bun. Validate the values with -`node:assert/strict` assertions. +Use `node:test` and `node:assert/strict` directly—Deno, Node.js, and Bun all +support these built-in modules, so they are the preferred choice for new +integration packages: -> **Warning**: `@fedify/fixture` is a **private** workspace package and -> must never be imported from published (non-test) source files. Only -> import it in `*.test.ts` files. +~~~~ typescript +import { describe, it } from "node:test"; +import { deepStrictEqual, ok } from "node:assert/strict"; +~~~~ If the framework relies on virtual modules, build-time code generation, -or other mechanisms that make `@fedify/fixture` impractical, you may use the +or other mechanisms that make `node:test` impractical, you may use the framework's own test utilities or a compatible test runner (e.g., `vitest`). Document the choice in the test file so future contributors understand why a different runner was chosen. +You can still import helpers from `@fedify/fixture` in `*.test.ts` files +when useful (e.g., `mockDocumentLoader`, `TestSpanExporter`). Just never +import `@fedify/fixture` from published (non-test) source files—it is a +private workspace package absent from the published artifacts. + #### Minimum test coverage At a minimum, test the following scenarios (see diff --git a/AGENTS.md b/AGENTS.md index 33d488532..57986f30b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,9 +108,10 @@ Code patterns and principles 3. **Type Safety**: Maintain strict TypeScript typing throughout. Use generics like `` to allow applications to customize context data. -4. **Testing**: Follow the existing test patterns. Tests use `@fedify/fixture` - which provides runtime-agnostic test adapters (wraps Deno, Node.js, and Bun - test APIs). Use in-memory stores for testing. +4. **Testing**: Follow the existing test patterns. Tests use `node:test` and + `node:assert/strict` (supported on Deno, Node.js, and Bun). Use in-memory + stores for testing. Exception: `@fedify/fedify` and `@fedify/vocab` use + `test()` from `@fedify/fixture` for Cloudflare Workers compatibility. 5. **Framework Agnostic**: Code should work across Deno, Node.js, and Bun environments. @@ -179,11 +180,12 @@ A detailed step-by-step guide is available across three skills: 3. Follow the pattern from existing database adapter packages 4. Implement both KV store and message queue interfaces as needed -### Writing tests with `@fedify/fixture` +### Writing tests -See *CONTRIBUTING.md* “Writing tests with `@fedify/fixture`” section and -*packages/fixture/README.md* for detailed instructions on using the fixture -package for runtime-agnostic testing. +See *CONTRIBUTING.md* “Writing tests with `node:test`” section and +*packages/fixture/README.md* for details on `@fedify/fixture` utilities +(`mockDocumentLoader`, `TestSpanExporter`, etc.) and the Cloudflare Workers +exception. ### Adding a new package @@ -207,10 +209,18 @@ Testing requirements 1. Write unit tests for all new functionality 2. Follow the pattern of existing tests -3. Import `test` from `@fedify/fixture` for runtime-agnostic tests -4. Use testing utilities from *packages/testing/* (`@fedify/testing`) or +3. Use `node:test` and `node:assert/strict` for tests in most packages—Deno, + Node.js, and Bun all support these built-in modules +4. **Exception**: `@fedify/fedify` and `@fedify/vocab` must use `test()` from + `@fedify/fixture` because those packages include a Cloudflare Workers test + harness that consumes the `testDefinitions` registry; using `node:test` + directly would bypass that harness +5. `mockDocumentLoader()` and `TestSpanExporter`/`createTestTracerProvider()` + from `@fedify/fixture` may be imported in any `*.test.ts` file regardless + of which test runner is used +6. Use testing utilities from *packages/testing/* (`@fedify/testing`) or *packages/fedify/src/testing/* (for Fedify-dependent utilities) -5. Consider interoperability with other fediverse software +7. Consider interoperability with other fediverse software Documentation standards diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c421d48f..8ff275fe8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -180,19 +180,54 @@ A patch set should include the following: Feature pull requests should target the *main* branch for non-breaking changes, or the *next* branch for breaking changes. -### Writing tests with `@fedify/fixture` +### Writing tests with `node:test` -The monorepo-private [`@fedify/fixture`] package provides the shared test -infrastructure used across every workspace package. Reach for it whenever you -add or modify a unit test: +Deno, Node.js, and Bun all support the `node:test` and `node:assert/strict` +built-in modules, so use them directly in new test files unless your package +requires Cloudflare Workers testing (see the exception below). + +A typical test file looks like this: + +~~~~ typescript +import { describe, it } from "node:test"; +import { deepStrictEqual, ok } from "node:assert/strict"; + +describe("my feature", () => { + it("does the thing", () => { + deepStrictEqual(1 + 1, 2); + }); +}); +~~~~ + +Run the tests with `mise run test:deno`, `mise run test:node`, or +`mise run test:bun` as appropriate. + +### Cloudflare Workers exception: `@fedify/fixture` + +The `@fedify/fedify` and `@fedify/vocab` packages must continue using the +`test()` function from the monorepo-private [`@fedify/fixture`] package. +Those packages include a Cloudflare Workers test harness +(*packages/fedify/src/cfworkers/*) that drives the test suite by iterating +over the `testDefinitions` array exported from `@fedify/fixture`. Using +`node:test` directly would not populate that array, breaking CF Workers tests. + +For these two packages, use the `@fedify/fixture` `test()` wrapper: + +~~~~ typescript +import { test } from "@fedify/fixture"; +import { deepStrictEqual } from "node:assert/strict"; + +test("my feature does the thing", () => { + deepStrictEqual(1 + 1, 2); +}); +~~~~ + +The `@fedify/fixture` package also provides utilities that any package can +import in `*.test.ts` files, regardless of which test runner is used: - - `test()`: A drop-in `Deno.test()`-compatible wrapper that runs the same - test on Deno, Node.js, Bun, and the Cloudflare Workers harness. - - `testDefinitions`: The array of every registered `test()`, consumed by - the Workers test runner. - `mockDocumentLoader()`: A document loader that resolves - ActivityPub/JSON-LD URLs from on-disk fixtures under - *packages/fixture/src/fixtures/* instead of issuing real HTTP requests. + ActivityPub/JSON-LD URLs from on-disk fixtures instead of issuing real + HTTP requests. - `TestSpanExporter`/`createTestTracerProvider()`: Helpers for asserting on OpenTelemetry spans and events recorded by the code under test.