chore: import upstream snapshot with attribution

skill-data/testing.md

@@ -0,0 +1,109 @@
+---
+name: testing
+description: Write and run Zero test blocks.
+---
+
+# Zero Testing
+
+Use this when adding tests, debugging failing tests, or wiring Zero checks into CI and editor workflows.
+
+## Test Blocks
+
+Zero test blocks live beside source:
+
+```zero
+fn add(left: i32, right: i32) -> i32 {
+    return left + right
+}
+
+test "addition works" {
+    expect add(2, 3) == 5
+}
+```
+
+`expect` requires a `Bool`. A false expectation fails the test.
+
+Use `std.testing` helpers when a predicate should be explicit in the source:
+
+```zero
+test "output shape" {
+    expect std.testing.equalBytes("zero", "zero")
+    expect std.testing.containsBytes("zerolang", "lang")
+}
+```
+
+`std.testing` does not register tests or print output. It only returns `Bool`
+values for ordinary `expect` statements.
+
+## Run
+
+```sh
+zero test conformance/native/pass/test-blocks.graph
+zero test --filter addition conformance/native/pass/test-blocks.graph
+zero test conformance/packages/test-app
+```
+
+Use `--filter` for a narrow loop. The filter matches test names by substring.
+
+For packages, normal `zero test [package]` compiles from `zero.graph` and can
+run before `.0` projections exist:
+
+```sh
+zero patch --op 'addTest name="addition works" call="add" arg0="2" arg1="3" expect="5" type="i32"'
+zero test
+zero test --filter addition
+```
+
+Prefer `addTest` for one pure function call with literal arguments. Use
+`addTestBody name="..." ... end` only when the test needs custom body rows.
+Test labels are display names, not callable function names; do not rename them
+to `__zero_test_*`.
+If `zero test` reports an unknown function for a display label, do not rename
+the label to chase runner internals. Delete the malformed custom test and
+recreate simple pure coverage with `addTest`, or use behavior smoke checks for
+effectful paths.
+
+If another tool hands you a derived ProgramGraph artifact, `zero test` can
+validate it. Do not create a standalone graph artifact for the ordinary package
+test loop; test the package path so the compiler reads `zero.graph` directly.
+
+## JSON Fields
+
+Use `zero test --json` when a tool or CI job needs exact fields. Useful fields:
+
+- `testDiscovery`: how files and tests were found
+- `fixtures`: fixture inputs and snapshot metadata
+- `snapshotKey`: stable test snapshot contract
+- `discoveredTests`, `selectedTests`, `passedTests`, `failedTests`
+- `expectedFailures`, `unexpectedPasses`
+- `targetFacts`: selected target and capability facts
+- `results`: per-test name, status, duration, source location, and failure span
+- `stdout`, `stderr`, `durationMs`
+
+Use JSON for machines and CI contracts. Normal test output is the default agent loop.
+
+## Expected Failures
+
+Expected-fail tests use one of these name markers:
+
+- `xfail:`
+- `expected fail:`
+- `[xfail]`
+
+Example:
+
+```zero
+test "xfail: pending parser edge case" {
+    expect false
+}
+```
+
+An expected-fail test passes the command only when it fails as expected. If it starts passing, the command fails with `unexpectedPasses`.
+
+## Agent Workflow
+
+1. Add the smallest test that owns the behavior.
+2. Run a filtered test while editing.
+3. Run the containing package or fixture before finishing.
+4. Do not leave an expected-fail marker on a fixed bug.
+5. Use `zero check` first when the failure is a compile error; rerun with `--json` only if you need exact diagnostic fields.