Java Testing Standards

Testing standards using JUnit 5, AssertJ, Mockito, Cucumber

by HoangNguyen0403 · MIT license · ★ 569 on GitHub

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…

---
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

Overview

Manual install (npx, ZIP)

Claude Codenpx skills add HoangNguyen0403/agent-skills-standard --skill java-testing -g -a claude-code

Claude Code (degit)npx degit HoangNguyen0403/agent-skills-standard/skills/java/java-testing#develop ~/.claude/skills/java-testing

Claude.ai / desktopZip the folder and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md4.1 KB

Read SKILL.md here

HoangNguyen0403/develop1 file shown

SKILL.md4.1 KB

Browse every file on GitHub↗

SKILL.md

Show the full text58 lines

java-testing/SKILL.md58 lines · 4.1 KB

PreviewCode

Outline

RawView on GitHub

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

1	---
2	name: java-testing
3	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.
4	metadata:
5	triggers:
6	files:
7	- '*/Test.java'
8	- '*/IT.java'
9	keywords:
10	- "@Test"
11	- "@ParameterizedTest"
12	- Mockito
13	- AssertJ
14	- assertThat
15	- JUnit
16	- Testcontainers
17	---
18	# Java Testing Standards
19
20	## Priority: P0 (CRITICAL)
21
22	## Core Rule Anchors
23
24	- `[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.
25	- `[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.
26	- `[BE-TEST-03]` Ban on Shallow Assertions: Never assert only `assertThat(result).isNotNull()` without inspecting domain fields, status codes, and invariants.
27	- `[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.
28	- `[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.
29
30	## Implementation Guidelines
31
32	- JUnit 5 (Jupiter): Use `@Test`, `@BeforeEach`, and `@AfterEach`. Avoid JUnit 4 classes.
33	- Fluent Assertions: Use `AssertJ (assertThat)` over JUnit `assertEquals` — enhanced readability.
34	- Naming: Use `MethodName_State_Result` or `@DisplayName("Check if X when Y")`.
35	- Parameterized Tests (`[BE-TEST-01]`): Use `@ParameterizedTest` with `@ValueSource`, `@CsvSource`, or `@MethodSource`.
36	- Mocking Strategy (`[BE-TEST-04]`): Use `Mockito` with `@ExtendWith(MockitoExtension.class)`. Use `@Mock`, `@Spy`, and `@InjectMocks`. NEVER mock data-only Records.
37	- Integration Testing (`[BE-TEST-02]`): Use `Testcontainers` with `@Container` for real databases (PostgreSQL/Redis) in integration tests (`*IT.java`).
38	- Isolation: Each test method MUST be isolated and independent; use `@DirtiesContext` sparingly.
39	- AssertJ Chaining (`[BE-TEST-03]`): Chain assertions for clarity: `assertThat(result).isNotNull().hasSize(2).contains("X")`.
40	- Mocking Verification: Audit observable contract outcomes and state changes; do not assert mock call counts or invocation sequences as a proxy for correctness.
41	- Exceptions: Use `assertThatThrownBy(() -> ...)` to verify specific Exception types and messages.
42	- Coverage: Coverage is diagnostic and project-configured; verify risk-weighted critical paths rather than padding code for an arbitrary percentage.
43
44	## Anti-Patterns
45
46	- `[BE-TEST-01]` Stylistic parameterized rewrites: Do not demand parameterized refactoring of passing tests without a behavioral gap.
47	- `[BE-TEST-02]` Brittle DB mock string matching: Do not match raw SQL strings in mocks; use Testcontainers.
48	- `[BE-TEST-03]` Shallow assertions: Never assert only `assertThat(result).isNotNull()` without domain inspection.
49	- `[BE-TEST-04]` Pass-through mock echoing: Ban 1:1 mock echoing without contract verification.
50	- `[BE-TEST-05]` Bug fix without reproduction test: Ban bug fixes without a regression test.
51	- No Logic in Tests: Keep tests declarative; no loops or if/else branching.
52	- No System.out in Tests: Use assertions; never print to stdout.
53	- No Legacy Assertions: Use `assertThat(a).isEqualTo(b)`, not `assertTrue(a == b)`.
54	- No Shared State: Tests must be isolated and order-independent.
55	## References
56
57	- [Full JUnit 5 + Mockito + AssertJ Template](references/junit-template.md)
58