test-runner

---

name: test-runner description: Run tests in the fdb-record-layer codebase, interpret results, and diagnose failures. Some example usages: "Run EmbeddedRelationalStatementTest" "Run the yaml integration tests" "Why is this test failing?" "Run the tests for the class I just modified"

Always apply the using-gradle skill for Gradle task syntax and build commands.

How to run tests

• For yaml-tests: ./gradlew :yaml-tests:test (or --tests 'YamlIntegrationTests.<name>').
• For embedded-only yaml-tests (faster): ./gradlew :yaml-tests:quickTest.
• For mixed-mode yaml-tests locally: ./gradlew :yaml-tests:mixedModeTest.
• For JUnit tests in a module: ./gradlew :<module>:test --tests '<fully.qualified.ClassName>'.

Diagnosing failures

1. Read the full test output — look for the stack trace and the assertion message.
2. Check if the failure is in a yaml test:
   • plan mismatch → the actual query plan changed; edit YamlIntegrationTests.java to add @MaintainYamlTestConfig(YamlTestConfigFilters.CORRECT_EXPECTATIONS) to the test entry, then re-run — the framework will auto-correct the expected plan.
   • result mismatch → data or query logic changed; inspect the yamsql file.
3. Check if the failure is an async issue:
   • BlockingInAsyncContextException → something called join()/get() inside a future.
   • Timeout → possible deadlock; check for blocking calls in completion lambdas.
4. Check if FDB connectivity is the issue:
   • FDBException or connection refused → FDB is not running or cluster file is wrong.