Java TestingSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: java-testing
description: Testing standards using JUnit 5, AssertJ, Mockito, Cucumber, and Spring Boot integration tests for Java. Use when writing or reviewing Java test behavior, including parallel execution and BDD; defer Kotlin-only tests, virtual-thread test infrastructure, and coverage-report/tooling configuration.
metadata:
  triggers:
    files:
    - '**/*Test.java'
    - '**/*IT.java'
    keywords:
    - "@Test"
    - "@ParameterizedTest"
    - Mockito
    - AssertJ
    - assertThat
    - JUnit
    - Testcontainers
---
# Java Testing Standards

## **Priority: P0 (CRITICAL)**

## Core Rule Anchors

- **`[BE-TEST-01]` Parameterized Tests for Equivalent Cases**: Prefer `@ParameterizedTest` (`@CsvSource`, `@MethodSource`) when methods have multiple equivalent inputs or boundary permutations. Distinct scenarios may stay separate test methods. Reviewers must not demand parameterized rewrites without a behavioral gap.
- **`[BE-TEST-02]` Ban on Brittle DB Mock String Matching**: Do not use string-matching mocks for raw SQL queries. Test pure domain calculations directly, or use `Testcontainers` for database repository verification.
- **`[BE-TEST-03]` Ban on Shallow Assertions**: Never assert only `assertThat(result).isNotNull()` without inspecting domain fields, status codes, and invariants.
- **`[BE-TEST-04]` Ban on Pass-Through Interface Mocks**: Repositories and service handlers must test contract compliance and error mapping. Ban 1:1 pass-through mock echoing without contract assertions.
- **`[BE-TEST-05]` Bug-First Regression Lock**: Every PR fixing a bug ticket or with title `fix(...)` must introduce a test reproducing the defect prior to the fix.

## Implementation Guidelines

- **JUnit 5 (Jupiter)**: Use **`@Test`**, **`@BeforeEach`**, and **`@AfterEach`**. Avoid JUnit 4 classes.
- **Fluent Assertions**: Use **`AssertJ (assertThat)`** over JUnit `assertEquals` — enhanced readability.
- **Naming**: Use **`MethodName_State_Result`** or **`@DisplayName("Check if X when Y")`**.
- **Parameterized Tests (`[BE-TEST-01]`)**: Use **`@ParameterizedTest`** with **`@ValueSource`**, **`@CsvSource`**, or **`@MethodSource`**.
- **Mocking Strategy (`[BE-TEST-04]`)**: Use **`Mockito`** with `@ExtendWith(MockitoExtension.class)`. Use **`@Mock`**, **`@Spy`**, and **`@InjectMocks`**. NEVER mock data-only Records.
- **Integration Testing (`[BE-TEST-02]`)**: Use **`Testcontainers`** with `@Container` for real databases (PostgreSQL/Redis) in integration tests (`*IT.java`).
- **Isolation**: Each test method MUST be isolated and independent; use **`@DirtiesContext`** sparingly.
- **AssertJ Chaining (`[BE-TEST-03]`)**: Chain assertions for clarity: **`assertThat(result).isNotNull().hasSize(2).contains("X")`**.
- **Mocking Verification**: Audit observable contract outcomes and state changes; do not assert mock call counts or invocation sequences as a proxy for correctness.
- **Exceptions**: Use **`assertThatThrownBy(() -> ...)`** to verify specific Exception types and messages.
- **Coverage**: Coverage is diagnostic and project-configured; verify risk-weighted critical paths rather than padding code for an arbitrary percentage.

## Anti-Patterns

- **`[BE-TEST-01]` Stylistic parameterized rewrites**: Do not demand parameterized refactoring of passing tests without a behavioral gap.
- **`[BE-TEST-02]` Brittle DB mock string matching**: Do not match raw SQL strings in mocks; use Testcontainers.
- **`[BE-TEST-03]` Shallow assertions**: Never assert only `assertThat(result).isNotNull()` without domain inspection.
- **`[BE-TEST-04]` Pass-through mock echoing**: Ban 1:1 mock echoing without contract verification.
- **`[BE-TEST-05]` Bug fix without reproduction test**: Ban bug fixes without a regression test.
- **No Logic in Tests**: Keep tests declarative; no loops or if/else branching.
- **No System.out in Tests**: Use assertions; never print to stdout.
- **No Legacy Assertions**: Use `assertThat(a).isEqualTo(b)`, not `assertTrue(a == b)`.
- **No Shared State**: Tests must be isolated and order-independent.
## References

- [Full JUnit 5 + Mockito + AssertJ Template](references/junit-template.md)

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.