# Testing

For this library the types _are_ the feature, so a runtime-only test loop would
verify the wrong thing. The commands are in
[CONTRIBUTING.md](../CONTRIBUTING.md); this file records why the loop is shaped
the way it is.

## Type-driven development

The rules — the loop and the pairing rule — are in
[CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
What follows is why and what was rejected.

#### Decision (2026-09)

The compile-time expectation is written before the runtime assertion, and both
before the implementation.

#### Why

- A runtime-only test can pass while the type is wrong, so a type-level library
  would ship a broken feature its tests bless.
- The type error is a more precise spec than a failing assertion, because it
  states the exact expected type before the logic exists.

#### Rejected

- Runtime-first (classic red/green): it verifies the value, not the contract,
  and the contract is the product.
- Testing the type only: it would not catch handler dispatch or the `_`
  fallback (see `src/primitive.test.ts`).

The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are in
[CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
`c8` uses V8 coverage, so the `--strip-types` source is instrumented without a
build step, and the runner relies on the `.ts` import-extension convention (see
[tooling.md](./tooling.md#source-imports-use-ts-extensions)).

## AAA ordering

The rule is in
[CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).

#### Decision (2026-09)

Test bodies read arrange → act → assert: inputs (the factory) set up first, the
subject exercised once from them, all checks last — types then runtime. The
blocks are labeled with `// Arrange` / `// Act` / `// Assert` comments and
separated by a blank line; an empty block drops its label.

#### Why

- Interleaved setup/checks hide what runs vs. what is observed; the eye
  re-reads the block to find the seams.
- A factory built mid-test invites a second throwaway call of the subject;
  arranging it once makes the positive construction and the negative
  `Parameters<…>` check share one source of truth.
- Labels make the seams explicit, not inferred — grep-able and reviewable
  without reading the statements.

#### Rejected

- Unlabeled ordering (bare blank lines): the seams still have to be found by
  reading; the labels cost nothing.

## Test helpers

The rule is enforced by `import/no-relative-parent-imports`; this section records
why the mechanism is shaped like this.

#### Decision (2026-09)

A shared test helper — code that scattered `*.test.ts` files import to do their
testing — lives under `src/util/__tests__/` and is addressed by the
`#test-utils/…` self-reference (`package.json#imports`:
`"#test-utils/*": "./src/util/__tests__/*"`), never by a relative path:

```ts
import { LspSession } from "#test-utils/lsp-completion.ts";
```

#### Why

- The lint rule bans upward (`../`) imports, and a cross-cutting helper can
  always be placed above _some_ scattered consumer, wherever it goes. Name
  beats path: a `#test-utils/…` specifier has no direction, so the rule never
  fires and file moves only touch the one mapping in `package.json`.
- `#…` is Node's reserved prefix for _private_ subpath imports: publishing
  `package.json` leaks nothing and resolves nothing for consumers.
- `__tests__` as the folder name is not about tests living there; it is the
  directory pattern `tsconfig.build.json` already excludes, so a helper can
  never be emitted into `dist/` and shipped by accident.
- Node's own resolver handles `#…` under `--strip-types`, and `tsc` resolves it
  via the same `imports` field — one mechanism for runtime and type gate, no
  loader needed.
- The helper uses `node:` builtins (it drives a language server), so
  `import/no-nodejs-modules` is off for `src/util/__tests__/**` in
  `.oxlintrc.json` — the same exception the old `scripts/**` scope carried.

#### Rejected

- A helper beside the tests (`src/util/test.ts`, flat `src/`): composes only
  while `src/` stays flat; the first nested test reaching it reintroduces the
  banned upward import.
- Bare `~/…` specifier: not valid in `imports` (keys must start with `#`) —
  resolution fails at runtime with `ERR_MODULE_NOT_FOUND`. A `#~/…` “home”
  shorthand was dropped in review; `#test-utils/…` states what it is.
- tsconfig `paths` alias: resolves for `tsc` but not for plain
  `node --test --strip-types` (no loader hook), breaking the fast tier.
- Turning `import/no-relative-parent-imports` off for test files: the rule
  still guards non-test helpers importing each other, and the exemption is
  only needed for the one specifier the mapping already solves cleanly.

## Known issues

- The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so
  test files that use it (`src/primitive.test.ts`) carry a
  file-level `oxlint-disable
typescript/no-floating-promises` with an explanatory comment. It is a known
  false positive, not a rule worth disabling project-wide (see
  [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).