.agents/rules/testing.md

# Testing & Validation Guardrails

## `--config=fast-tests` for Test Targets
* Always pass `--config=fast-tests` when running or building test targets to
  avoid running expensive, flaky integration tests.

## Running Integration Tests Directly
* Integration tests under `tests/integration/` are tagged
  `["integration-test", "enormous"]` and are filtered out by
  `--config=fast-tests`.
* To run a specific integration test target directly, omit
  `--config=fast-tests`: `bazel test //tests/integration:<target>`.

## CRITICAL: Never use `--config=fast-tests` on Non-Test Targets
* `--config=fast-tests` sets `--build_tests_only=true`, which silently ignores
  non-test targets (such as `//docs:docs` or package libraries), resulting in 0
  targets built!

## Lockfile Testing (`MODULE.bazel.lock`)
* Changes to transitive module extension dependencies or `.bzl` files loaded by
  extensions update Bazel 9 lockfile hashes, requiring `bazel mod deps
  --lockfile_mode=update` in integration test workspaces.
* When requirements files (e.g., in `//tools/publish` or root pip parses) are
  modified or bumped by Dependabot, update the integration lockfile by running
  `bazel mod deps --lockfile_mode=update` in `tests/integration/bzlmod_lockfile`
  and verify with
  `bazel test //tests/integration:bzlmod_lockfile_test_bazel_9.1.0`.

## Documentation Flake Handling
* When building `//docs:docs` fails with exit code 2, treat it as a known
  Sphinx/Bazel flake and retry the build.

## Test Organization
* **Domain Placement**: Place tests by the feature tested (e.g.,
  `tests/bootstrap_impls/`), not by the fixture helper used (e.g.,
  `py_extension`).
* **Platform Constraints**: Restrict OS-specific targets with
  `target_compatible_with` (e.g., `["@platforms//os:windows"]`) to skip on
  incompatible platforms.
* **Multi-version `pytest_test`**: Restrict targets using `python_versions` to
  Bzlmod with `target_compatible_with = SUPPORTS_BZLMOD`
  (`//tests/support:support.bzl`). WORKSPACE mode resolves pip dependencies for
  only the host Python version.