conditional-testing

name	conditional_testing
description	Documentation for conditional testing in V8 using gm.py.

Skill: Conditional Testing

This skill documents how to use conditional testing to optimize the testing workflow in V8.

Purpose

Running the full V8 test suite can be time-consuming. Conditional testing saves time and resources by checking if tests are actually needed. It will build and/or run tests only if:

1. d8 executable is missing or out of date relative to modified source files (detected via git diff and git ls-files).
2. The d8 executable is newer than the last successful test run.
3. Any test file has been modified since the last successful test run.

Usage

Default Behavior

For regular users, conditional testing is enabled by default when executing a full test suite (e.g. check).

gm.py x64.release.check

If nothing has changed, it will silently exit without rebuilding or re-running tests. If only test files changed, it will re-run the tests without building. If you explicitly request a subset of tests (e.g., gm.py x64.release mjsunit/foo), the tests will run unconditionally.

Agent Workflow

For automated agents, you can use the --ensure-tests-ran flag without specifying a target configuration. This will automatically detect the most recently built configuration in out/ and run the tests (if needed) for that specific configuration.

tools/dev/gm.py --ensure-tests-ran

How It Works

1. Checks Modified Files: Uses git diff origin/main and git ls-files --others to efficiently find files modified in the worktree.
2. Checks Build Need: If any C++, GN, or Bazel files (excluding test/ and tools/ directories) are modified since d8 was last built, a build is triggered.
3. Checks Timestamps: Compares the modification time of d8 with a cached timestamp in <outdir>/last_test_run. If d8 is newer, tests are run.
4. Checks Test Need: If any file in the test/ directory is newer than last_test_run, tests are run.
5. Updates Timestamp: On a successful full test run, it updates the <outdir>/last_test_run file timestamp.

Best Practices

• Always rely on gm.py --ensure-tests-ran for background checking.
• If you want to force a full test run, you can either touch d8 or remove the last_test_run file.