tests

Imported from samuelmasse/AlvorKit (tests/AGENTS.md). Install upstream with npx skills add samuelmasse/AlvorKit --skill tests. Copyright stays with the author.

Tests Instructions

Scope

These instructions apply to all test projects under tests/.

This file is a delta over the root instructions. Before changing C#, read ../docs/AgentRules/CSharp.md. Also read the subject policy for the behavior under test, such as runtime performance, facades, generated bindings, hashing, or project structure. A sibling src/AGENTS.md or scripts/AGENTS.md is not automatically in scope for this tree.

Shared Test Code

• Keep tests/ for runnable test projects; shared helper libraries belong in src/.
• Name runnable test projects with the .Test suffix so Directory.Build.props gives them MSTest, coverage, and the shared helper reference.
• Add a concise XML <summary> doc comment to each runnable test method.
• Use AlvorKit.Testing for cross-project fixtures such as temporary workspaces, disposable filesystem setup, and small repository/project writers.
• When the same helper shape appears in more than one test project, move it to src/AlvorKit.Testing before adding the second copy.
• Keep project-specific harnesses local when they depend on one source project's internals or make sense only for that project.
• Favor explicit fixture builders that remove repeated setup without hiding the assertion being tested.

Test Quality

• These rules apply whenever writing tests.
• Do not add coverage-only smoke bundles that merely call many APIs. Each runnable test should assert observable state, generated output, returned data, or a specific exception.
• If a coverage sweep is unavoidable, keep it small and state the behavioral invariant it protects in the test summary.
• When adding repository config fixtures, prefer shared helpers from AlvorKit.Testing over copied YAML/JSON writer methods.
• When changing a repository-owned config format, replace old fixtures and tests with the current format. Keep multiple formats only when an explicit external interoperability contract or a shipped-project policy requires them.
• Tests for generated artifact names, output directories, or run IDs should use meaningful identifiers such as native library names, not generic filenames like bindgen.

Visual Test Harnesses

• Prefer direct unit tests for deterministic behavior.
• When a visual game smoke check is needed and the target is wired with AgentGlfwWindowHost from AlvorKit.Windowing.Agent, use the root AlvorSense guidance. Verify real desktop window and input behavior manually or with purpose-built external tooling.

Commit Mode Verification

• For C# test changes, run focused coverage for the affected source project with --source-project, adding --test-project only when an explicit test project choice is useful, then run scoped lint.
• For generated binding test changes, run focused coverage with --binding using the native library name and --threshold 0, such as fastnoise2, and inspect missing generated API and .Backend coverage before handoff.
• If shared helper behavior changes across many projects, prefer the full strict coverage gate before handoff.