Testing and simulation

Testing is how we keep the template safe to extend. The goal is not perfect coverage. The goal is catching the mistakes that waste practice time and break matches.

Unit tests

Run:

./gradlew test

The existing tests cover pure logic such as:

• alliance transforms
• BLine asset lookup
• auto chooser validation logic
• field target transforms
• DriveToPose completion behavior
• degenerate tuning values
• vision acceptance/rejection filtering

When you add pure logic, add tests. Good candidates are transforms, constraints, command finish conditions, event lookup, and configuration validation.

Build

Run:

./gradlew build

The build also runs formatting through the current Gradle configuration. If formatting changes files, review them before committing.

Desktop simulation

Run:

./gradlew simulateJava

Use simulation to verify:

• robot code starts
• commands bind
• default drive command schedules
• BLine autos load
• PathPlanner navigation commands construct
• PhotonVision sim plumbing is connected
• logs contain expected topics

Simulation can expose code wiring problems. It cannot prove the real robot is mechanically correct.

Replay checks

Replay lets you run code over recorded logs with hardware IO disabled. Use it when debugging estimator outputs, command decisions, and derived logging.

Run the replay workflow configured by the project:

./gradlew replayWatch

Keep constructors and commands replay-safe. If replay tries to open a motor controller or camera, the IO boundary was crossed in the wrong place.

On-block checks

Before the robot touches carpet:

• lift the robot safely
• verify disable stops outputs
• check each module steering direction
• check each wheel drive direction
• check gyro yaw direction
• check field-relative translation
• check X-lock
• check current draw
• check logs

Do not test a newly configured swerve at full speed on the floor first.

Carpet checks

On carpet, start slow:

1. Drive robot-relative.
2. Drive field-relative.
3. Rotate in place.
4. Drive a measured distance.
5. Compare odometry to reality.
6. Test slow mode.
7. Test heading reset.
8. Test one simple auto path.
9. Test teleop navigation cancellation.

Only increase constraints after the logs match what the robot physically did.

Docs build

The documentation site should build strictly:

pip install -r docs/requirements.txt
mkdocs build --strict

Strict docs builds catch broken internal links and navigation mistakes before GitHub Pages deploys a bad site.

CI expectations

The robot build workflow should continue to build robot code. The docs workflow should build docs on pull requests and deploy Pages from main.

Keep these workflows separate. Robot code needs the WPILib build environment. Docs only need Python and MkDocs.

What to test after common edits

Edit	Minimum check
CTRE constants	build, sim start, on-block module check
module offsets	on-block steering check, slow carpet drive
wheel radius	measured distance test, autonomous path check
camera transform	PhotonVision pose check, accepted/rejected log review
BLine path JSON	unit tests, sim load, low-speed auto
event command	unit/sim if possible, timeout behavior
new subsystem	build, logging check, replay safety, command finish behavior
dashboard topic	AdvantageKit log and NT4 dashboard visibility