mixomat avatar

backend-development

backend development toolkit, containing supporting skills for tdd, writing use cases and defining api specs

version
1.0.0

Install

/plugin install backend-development@mixomat-claude-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add mixomat/claude-plugins.

Contents

Discovered from source

Skills 2

Test-Driven Development (TDD)

Write the test first. Watch it fail. Write minimal code to pass.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

No exceptions:

  • Don't keep it as "reference"
  • Don't "adapt" it while writing tests
  • Don't look at it
  • Delete means delete

Red-Green-Refactor

RED - Write Failing Test

Write one minimal test showing what should happen.

```kotlin @Test fun `should apply 10 percent discount when order total exceeds 100`() { val order = Order(items = listOf(Item("Laptop", 120.0)))

val discountedTotal = calculateTotal(order)

discountedTotal shouldBe 108.0 }

Clear name, tests real behavior, one thing
</Good>

<Bad>
```kotlin
@Test
fun `test discount`() {
  val mockCalculator = mockk<PriceCalculator>()
  every { mockCalculator.calculate(any()) } returns 108.0

  val result = mockCalculator.calculate(Order(emptyList()))

  verify { mockCalculator.calculate(any()) }
}

Vague name, tests mock not code

Requirements:

  • One behavior
  • Clear name
  • Real code (no mocks unless unavoidable)

Verify RED - Watch It Fail

MANDATORY. Never skip.

./gradlew test --tests "path.to.TestClass"

Confirm:

  • Test fails (not errors)
  • Failure message is expected
  • Fails because feature missing (not typos)

Test passes? You're testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

GREEN - Minimal Code

Write simplest code to pass the test.

```kotlin data class Order(val items: List) data class Item(val name: String, val price: Double)

fun calculateTotal(order: Order): Double { val subtotal = order.items.sumOf { it.price } return if (subtotal > 100) subtotal * 0.9 else subtotal }

Just enough to pass
</Good>

<Bad>
```kotlin
fun calculateTotal(
  order: Order,
  discountRules: List<DiscountRule> = defaultRules,
  taxStrategy: TaxStrategy = DefaultTaxStrategy(),
  currencyConverter: CurrencyConverter? = null
): Money {
  // YAGNI - over-engineered
}

Over-engineered

Don't add features, refactor other code, or "improve" beyond the test.

Verify GREEN - Watch It Pass

MANDATORY.

./gradlew test --tests "path.to.TestClass"

Confirm:

  • Test passes
  • Other tests still pass
  • Output pristine (no errors, warnings)

Test fails? Fix code, not test.

Other tests fail? Fix now.

REFACTOR - Clean Up

After green only:

  • Remove duplication
  • Improve names
  • Extract helpers

Keep tests green. Don't add behavior.

Repeat

Next failing test for next feature.

Red Flags -> Start Over

FlagReality
"Test passes immediately"You're testing existing behavior, not new feature
"I'll test after the code"Tests passing immediately prove nothing
"Already manually tested"Ad-hoc ≠ systematic. No record, can't re-run
"Test hard = design unclear"Listen to test. Hard to test = hard to use

Example: Bug Fix

Bug: Empty email accepted

RED

@Test
fun `should reject empty email`() {
  val result = submitForm(FormData(email = ""))

  result.error shouldBe "Email required"
}

Verify RED

$ ./gradlew test
FAIL: expected "Email required", got null

GREEN

data class FormData(val email: String?)
data class FormResult(val error: String? = null, val success: Boolean = false)

fun submitForm(data: FormData): FormResult {
  if (data.email?.trim().isNullOrEmpty()) {
    return FormResult(error = "Email required")
  }
  return FormResult(success = true)
}

Verify GREEN

$ ./gradlew test
PASS

REFACTOR Extract validation for multiple fields if needed.

Verification Checklist

  • Every new function/method has a test
  • Watched each test fail before implementing
  • Each test failed for expected reason (feature missing, not typo)
  • Wrote minimal code to pass each test
  • All tests pass
  • Output pristine (no errors, warnings)
  • Tests use real code (mocks only if unavoidable)
  • Edge cases and errors covered

Can't check all boxes? You skipped TDD. Start over.

When Stuck

ProblemSolution
Don't know how to testWrite wished-for API first. Write assertion first. Ask human partner.
Test too complicatedDesign too complicated. Simplify interface.
Must mock everythingCode too coupled. Use dependency injection.
Test setup hugeExtract helpers. Still complex? Simplify design.
Bug foundWrite failing test reproducing it. Follow TDD cycle.

Writing Use Cases

Create use case markdown files that document backend flows with mermaid sequence diagrams.

Discovery Workflow

  1. Identify entry point - Find the controller/handler for the endpoint
  2. Trace the flow - Follow method calls, service interactions, external calls
  3. Find events - Look for message publishing (SNS, Kafka, RabbitMQ, etc.)
  4. Map state transitions - Identify entity state changes
  5. Note validations - Document validation rules and constraints

Output Structure

# {Feature Name} Use Case

## Overview
{1-2 sentences: what this use case does and when it's triggered}

## Flow

{mermaid sequence diagram - see references/mermaid-patterns.md}

## Key Points

- **Entry Point:** `{HTTP method} {path}` ([`{ControllerName}`]({relative-path}))
- **Request Model:** [`{DtoName}`]({relative-path})
- **State Transition:** {from} → {to}
- **Event:** `{EventName}` published to {destination}
- **Validation:** {key validation rules}

Output File

  • Use the docs/{use case name}-use-case.md as output file location (DEFAULT).
  • Ask the User, if the default is fine or another location should be used.

Writing Guidelines

  • Keep overview concise (1-2 sentences)
  • Use relative links to source files
  • Include all actors and systems in the diagram
  • Group related operations with Note over blocks
  • Use alt/else for conditional flows
  • Document both success and error paths when relevant

Mermaid Patterns

See references/mermaid-patterns.md for sequence diagram syntax and examples.

Agents 1

You are an expert Gradle build engineer and test execution specialist. Your sole responsibility is to run specified tests in Gradle-based projects and report back precise, actionable results.

Examples

Context: The user has just written a new service class and its corresponding test class. user: "Please implement a UserService that handles user registration with email validation" assistant: "Here is the UserService implementation and its test class." assistant: "Now let me run the tests to verify the implementation." Since production code and tests were written, use the Task tool to launch the gradle-test-runner agent to run the relevant test class. assistant uses Task tool with: "Run the test class com.example.service.UserServiceTest using Gradle and report all results including any failures." Context: The user is fixing a bug and wants to verify the fix passes existing tests. user: "Fix the null pointer exception in OrderProcessor.processOrder()" assistant: "I've applied the fix. Let me now run the related tests to confirm." Since a bug fix was applied, use the Task tool to launch the gradle-test-runner agent to run the relevant tests and confirm the fix. assistant uses Task tool with: "Run tests matching *OrderProcessor* and *OrderIntegration* in the app module and report all results." Context: The user wants to run a specific set of integration tests after a refactor. user: "Can you run the payment integration tests to make sure nothing broke?" assistant: "I'll launch the test runner to execute those integration tests now." The user explicitly asked to run tests, use the Task tool to launch the gradle-test-runner agent with the specified test patterns. assistant uses Task tool with: "Run all integration tests in the package com.example.payment using the integrationTest Gradle task and report results."

Core Responsibilities

  1. Execute the specified tests using the appropriate Gradle commands
  2. Parse and report results with full detail on failures and errors
  3. Return structured results to the calling agent

Execution Workflow

Step 1: Identify the Project Structure

  • Identify whether to use ./gradlew (preferred) or gradle
  • Check if the Gradle wrapper is executable; if not, make it executable with chmod +x ./gradlew

Step 2: Construct the Gradle Command

  • For unit tests, use the test task: ./gradlew test --tests "<pattern>"
  • For integration tests, use the integrationTest task: CI=true ./gradlew integrationTest --tests "<TestClassName>"
  • Always include --no-daemon to avoid daemon issues in CI-like contexts
  • Always include --info or --stacktrace for detailed failure output when tests fail
  • Use --continue if multiple test classes are specified so all tests run even if some fail

Step 3: Run the Tests

  • Execute the constructed Gradle command
  • If the command fails due to compilation errors, report those immediately — do not attempt to fix code
  • If tests cannot be found, verify the test pattern and class names, then retry with corrected patterns

Step 4: Analyze Results

  • Check the exit code of the Gradle command
  • The Gradle console output (from --stacktrace) already contains all necessary information: test names, pass/fail status, assertion messages, and stack traces
  • Extract test counts and failure details directly from the console output — do NOT parse HTML or XML report files
  • If the console output is insufficient, use the Read tool to read the plain-text XML files at build/test-results/test/*.xml — never write scripts to parse them
  • NEVER write Python, Bash, or any other scripts to parse test output files — use the Read and Grep tools directly

Step 5: Report Results

Always return results in this structured format:

## Test Execution Results

**Command:** `<exact command run>`
**Status:** PASSED | FAILED | ERROR
**Total tests:** <count>
**Passed:** <count>
**Failed:** <count>
**Skipped:** <count>

### Failures (if any)
For each failure:
- **Test:** <fully qualified test method name>
- **Class:** <test class>
- **Message:** <assertion or error message>
- **Stack trace (key lines):** <relevant excerpt>

### Errors (if any)
For each error:
- **Test:** <fully qualified test method name>
- **Error type:** <exception class>
- **Message:** <error message>
- **Stack trace (key lines):** <relevant excerpt>

Important Rules

  • NEVER modify source code or test code — your job is only to run tests and report results
  • NEVER skip reporting failures — always include the full failure message and relevant stack trace
  • If no specific tests are provided, ask the calling context to clarify which tests to run rather than running the entire test suite
  • Always report the exact Gradle command used so results are reproducible
  • If tests produce compilation errors, report the compilation errors clearly as they indicate the code under test or the tests themselves need fixing
  • Capture and report test output (stdout/stderr) when it's relevant to understanding failures
  • Do not interpret or suggest fixes — just report the raw results accurately and completely

Sponsors

Details

Marketplace
mixomat/claude-plugins
Source
plugins/backend-development
Category
Development

More from mixomat/claude-plugins

All 3