xtdb-testing

Governs Gradle test delegation, edit freezes, and fixture regeneration for XTDB.

3.0k|192|Updated Mar 19, 2018
One-click install
npx skills add https://github.com/xtdb/xtdb --skill xtdb-testing
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: xtdb-testing
Source: https://github.com/xtdb/xtdb/tree/main/.claude/skills/xtdb-testing
Command: npx skills add https://github.com/xtdb/xtdb --skill xtdb-testing

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Running tests in the XTDB repository involves non-obvious rules — delegating to the gradle-tests agent, respecting the mid-run compile freeze, choosing the right Gradle task and iteration property, and handling simulation tests and golden fixtures — and getting any of them wrong produces bogus failures or false green results.

Core Features & Use Cases

  • Test delegation rules: All test runs go through the gradle-tests agent with explicit no-edit instructions, one concurrent run maximum, and invalidated runs stopped immediately.
  • Build-phase freeze mechanics: Defines which files are frozen during compilation, how to split compile and test phases to keep working, and why module Clojure sources stay live on the classpath.
  • Task and filter reference: Covers Gradle test tasks (test, integration-test, property-test, kafka-test, nightly-test), module addressing, --tests patterns with underscores, and the two independent iteration knobs (-Piterations vs -PsimulationIterations).
  • Failure and fixture handling: Enforces the "you broke it" policy with a narrow flaky-issue carve-out, and documents the arrow-edn golden fixture regeneration workflow with its gotchas.
  • Use Case: After changing compaction code, you learn that simulation tests are invisible to ./gradlew test, so you run ./gradlew property-test with -PsimulationIterations=500 and verify the actual iteration count in the output.

Quick Start

Read this skill before running or delegating any XTDB test run, then delegate the run to the gradle-tests agent with an explicit instruction not to modify any files.

Frequently Asked Questions about xtdb-testing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run tests in the XTDB repository?

Delegate every test run to the gradle-tests agent via the Task tool, stating explicitly that it must run and report only without modifying files. Never run tests yourself or use repl-explorer, and launch only one gradle-tests agent at a time.

How do I run a single Clojure test namespace with Gradle?

Use ./gradlew :test --tests 'xtdb.api_test*' with underscores instead of dashes in the namespace pattern. Add --rerun-tasks when re-executing the same invocation, since Gradle caches repeated --tests runs as UP-TO-DATE.

Why does -Piterations not increase simulation test iterations?

-Piterations only drives the Clojure test.check properties; Kotlin simulation tests read -PsimulationIterations instead. Passing -Piterations=500 to a simulation run still executes 100 iterations per method, so verify the actual count in the test output.

Can I edit source files while a Gradle test run is in progress?

No — editing files the build compiles during the compile phase causes bogus cross-language type errors. Either wait, or pre-run ./gradlew :testClasses yourself, then delegate the test run so its compile tasks are up-to-date and you can edit safely.

What should I do when a test fails after my change?

Treat the failure as caused by your change: all tests pass on main and there are no pre-existing failures. The only exception is a matching open GitHub issue labelled flaky; otherwise investigate your diff and fix the bug without disabling assertions.

How do I regenerate arrow-edn golden fixtures in XTDB?

Uncomment the #_aet/wrap-regen line in the namespace's use-fixtures, run with --rerun-tasks, then copy the regenerated files from build/resources/test back into src/test/resources. Re-comment the toggle and re-run to verify, since a regen run is trivially green.