Skip to content

po4yka/RIPDPI / .agents/skills/ripdpi-tdd

ripdpi-tdd

Verified

Red-green-refactor workflow for RIPDPI plus test-double and FaultQueue conventions. Use when the user asks for test-first work or a defect needs a reproducing test. Not for Kotlin test syntax (use kotlin-test-patterns).

Test-Driven Development

Full test stack documentation: docs/testing.md. Do not duplicate it here -- read it when you need runner details, CI lanes, or fixture locations. The test rule and the verification policy in AGENTS.md take precedence over this skill.

When to use the cycle

Use red-green-refactor when the user asks for test-first work, or when a defect or new behavior is not caught by an existing test. Search the owning module's tests first: if an existing test covers the behavior, extend it or rely on it instead of adding one. Refactors, renames, and wiring changes need no new test; the existing tests and the module gate prove them.

Workflow

  1. RED -- Write one test for one behavior and run only that test. Confirm it fails for the expected reason. If it passes, the behavior is already covered or the test is wrong.
  2. GREEN -- Write the minimum implementation that makes it pass. Run the same test again.
  3. REFACTOR -- Clean up the test and the implementation, then run the owning module's tests once.

Run the gate that AGENTS.md assigns to the change once, after the last cycle of a batch, not after every cycle.

Running Tests

Kotlin/JVM (fast iteration)

# Single test method
./gradlew :core:engine:testDebugUnitTest --tests "ClassName.method name"

# Single test class
./gradlew :core:engine:testDebugUnitTest --tests "ClassName"

# Single module
./gradlew :core:engine:testDebugUnitTest

Replace :core:engine with the target module (:core:service, :core:data, :core:diagnostics). :app tasks are flavor-qualified (:app:testGithubDebugUnitTest).

Rust

# Single test
cargo nextest run --locked -p crate_name test_name

# Single crate
cargo nextest run --locked -p crate_name

Golden contracts

Golden tests are read-only by default. Blessing needs explicit user approval for the affected fixture family; follow golden-bless-discipline.md and the golden-test-management skill.

Test Double Conventions

Fake* classes (no mocking frameworks)

The project uses hand-written Fakes and no MockK, Mockito, or other mocking library. Reuse an existing Fake from the owning module's tests before writing one; shared :core:engine doubles live in core/engine/src/test/kotlin/com/poyka/ripdpi/core/TestDoubles.kt.

  • Name: Fake + interface name (e.g., FakeRipDpiProxyRuntime)
  • Return configurable values set before the test runs
  • Assert the observable result of the code under test. Assert a recorded call only when the call itself is the behavior (for example, that a native stop was requested)

FaultQueue for fault injection

Fault injection uses FaultQueue<T> from core/engine-api/src/main/kotlin/com/poyka/ripdpi/core/testing/FaultModel.kt.

Key types:

  • FaultQueue<T> -- ordered queue of faults matched by target enum
  • FaultSpec<T> -- target + outcome + scope + optional message/payload
  • FaultScope.ONE_SHOT -- fires once then is consumed
  • FaultScope.PERSISTENT -- fires on every matching call until cleared
  • FaultOutcome -- EXCEPTION, TIMEOUT, DROP, RESET, MALFORMED_PAYLOAD, BLANK_PAYLOAD, PANIC

Usage in tests:

val bindings = FakeRipDpiProxyBindings()
bindings.faults.enqueue(
    FaultSpec(
        target = ProxyBindingFaultTarget.START,
        outcome = FaultOutcome.EXCEPTION,
        message = "simulated native crash",
    )
)

Test Organization by Layer

What you testLocationRunner
Kotlin business logiccore/*/src/test/./gradlew :core:*:testDebugUnitTest
Rust native logicnative/rust/crates/*/tests/cargo nextest run --locked -p crate
JNI integrationapp/src/androidTest/.../integration/connectedGithubDebugAndroidTest
Network E2Eapp/src/androidTest/.../e2e/connectedGithubDebugAndroidTest
Rust network E2Enative/rust/crates/*/tests/bash scripts/ci/run-rust-network-e2e.sh

Rules

  1. Fake doubles only.* No mocking frameworks.
  2. FaultQueue for error paths. Use FaultSpec + FaultQueue, not ad-hoc exception throwing.
  3. Use backtick names in Kotlin tests. @Test fun proxy start propagates native exception().
  4. Use snake_case names in Rust tests. fn proxy_start_propagates_native_exception().
  5. Test and implementation land in one commit. Never commit a test without its implementation or vice versa.
  6. Prefer unit tests. Escalate to integration or E2E only when the behavior needs real Android or network components.

Common Mistakes

MistakeFix
Using MockK or MockitoWrite or reuse a Fake* class
Adding a test an existing test already coversExtend or rely on the existing test
Asserting only a Fake's recorded callsAssert the observable result
runBlocking in coroutine testsUse runTest from kotlinx-coroutines-test
Testing private internalsTest through the public API of the class under test
FaultScope.PERSISTENT when ONE_SHOT sufficesDefault to ONE_SHOT; use PERSISTENT only for repeated-call scenarios

For deeper coverage of anti-patterns, see references/testing-anti-patterns.md.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 321kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 321kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 321kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall