Spring Project Testing

Test Layers and Placement

• Prefer the repository’s existing modules, naming conventions, test plugins, and CI layers. Propose a new structure only when no convention exists.
• Test layers are defined by startup scope and dependency realism, not by directory names such as

  core

  ,

  web

  , or

  api

  .
• Start with the lowest layer that can prove the risk. Do not use E2E to cover every branch, and do not claim that mocks prove middleware behavior.
• If a requirement spec already exists, fill the test layer, test case placement, and external dependencies back into the AC verification mapping. This skill does not manage requirement status.

Infrastructure Selection

• Business collaboration: When verifying call conditions, parameters, return values, and exception branches, mock databases, Redis, MQ, or remote services.
• Infrastructure semantics: When verifying SQL dialects, transactions, locks, Redis Lua/TTL, message serialization, or client behavior, use isolated instances that match production semantics. Testcontainers is a common choice, but not the only one.
• Topology behavior: When a Cluster, dual cell, network, or vendor-specific middleware cannot be represented by a single container, use an explicitly specified isolated environment. Tests must use unique prefixes and clean up data; never write automatically to production or shared business data.
• Configuration center: By default, use test properties or configuration stubs. Connect to a real configuration center only when configuration loading, group/namespace isolation, or hot reload itself is the target.
• No Docker: Depending on the target, choose among remote containers, embedded services, isolated environments, and pure mocks, and document the risks that remain uncovered. See docker-host-options.md.

Implementation Workflow (Read References as Needed)

1. Inventory the behaviors to prove, failure modes, and existing test structure.
2. Start at Tier 1 and move up only when the current layer cannot prove the risk.
3. See slice-tests.md for MVC slice isolation and context pitfalls.
4. See testcontainers-integration.md for integration approaches involving real databases, Redis, and similar systems.
5. See e2e-pytest.md for black-box HTTP testing and environment gates.
6. Read lbs-cloud-service-test.md only when the project depends on

   com.sf.lbs.cloud.*

   and encounters a corresponding issue.

Engineering Conventions

• Tests should be executable by default through standard test commands. Do not permanently skip tests in module configuration. If a pipeline has already performed verification in an earlier stage, a later packaging-only stage may skip repeated execution according to repository conventions, provided that dependency is explicit.
• When Maven uses JUnit 5, Surefire should be at least 2.22. Prefer the project BOM’s specific version, and confirm that tests actually ran and that the test count is not 0; a successful build alone is insufficient.
• For Gradle, also confirm that the test engine actually discovers the test cases.
• Prefer the project BOM and production-compatible version ranges for Testcontainers, databases, and middleware. Do not pin the latest versions in this general-purpose skill.
• Follow the repository’s conventions for test case naming and comments. Descriptions should reveal the scenario and expected outcome from failure output; do not impose a single comment format on every project.
• Do not change production visibility or introduce wrappers with no business value solely to simplify testing. Reasonable separation of responsibilities may be used to improve testability.

Acceptance Criteria

• Unit and slice tests should be fast, deterministic, and independent of shared environments. Integration tests should preserve the production constraints being verified while isolating data.
• Optional local E2E tests may be explicitly skipped when the environment is unreachable; CI/SIT/release gates must fail when they declare the target environment as mandatory.
• The final report must state which layer proves each risk and which external behaviors remain uncovered, preventing a “BUILD SUCCESS but no tests ran” outcome.