yq-stable-tests

Reliable CI tests

Build tests that remain correct under the repository's real CI topology, not only when run alone on a quiet workstation. This skill owns isolation and reliability decisions; it does not replace the repository's test-tier policy or select every command for a push.

Read the owning rules

• Use the target repository's testing policy to select unit, coverage, expected-output, snapshot, browser, or real-API evidence.
• Use the defensive patterns for lifecycle, subprocess, cancellation, and teardown behavior.
• Read the active Vitest config and GitHub workflow when their worker or job topology affects the test.
• Use pre-push-checks after the test design is sound to select outgoing validation.

Model the execution topology

Assume these layers can overlap unless the active configuration proves otherwise:

1. Tests in one Vitest file.
2. Separate Vitest files or worker processes.
3. Independent Vitest or repository-gate processes in one job.
4. Different Actions jobs whose runners share one host.

Process isolation does not isolate host ports, predictable filesystem paths, external services, databases, sockets, or inherited child processes. For every acquired resource, identify its owner, atomic allocation mechanism, observable readiness signal, registered cleanup, and quiescent completion signal.

Do not serialize an entire suite merely because one fixture lacks isolation. Narrow the exclusive scope or change the resource allocation first. A sequential Vitest block cannot protect a host resource from another file, process, job, or runner.

Allocate resources atomically

Use the resource owner's allocator instead of checking availability and claiming it later.

• Network fixtures bind loopback with listen(0) and read the assigned address only after the server reports that it is listening. Never scan for a free port and bind it later.
• Create private per-test temporary roots with mkdtemp; do not acquire predictable shared paths.
• Give shared databases, sockets, sessions, and output locations unique per-test namespaces.
• Use exclusive creation where a path must not already exist.
• Keep stable recorded identifiers separate from ephemeral transport addresses. Translate inside the fixture instead of forcing the live resource to use the recorded value.