---

description: JUnit 5 testing patterns, unit vs integration, BaseIntegrationTest, JaCoCo

globs: "src/test/**/*.java"

---

# Testing Rules – Contentstack Java CDA SDK

Apply when writing or editing tests. The project uses **JUnit 5** and **JaCoCo** (see `pom.xml`).

## Test naming and layout

- **Unit tests:** Class name prefix **`Test`** (e.g. `TestEntry`, `TestConfig`). Place in `src/test/java/com/contentstack/sdk/`.

- **Integration tests:** Class name suffix **`IT`** (e.g. `ContentstackIT`, `SyncStackIT`). Same package. Use **`BaseIntegrationTest`** for shared setup and timeouts.

## JUnit 5 usage

- Use **JUnit 5** (Jupiter) APIs: `@Test`, `@BeforeAll`, `@AfterAll`, `@BeforeEach`, `@AfterEach`, `@DisplayName`, etc.

- Prefer **`TestInstance(Lifecycle.PER_CLASS)`** when sharing a single instance across tests (e.g. `BaseIntegrationTest`).

- Use **assertions** from `org.junit.jupiter.api.Assertions`.

## Integration test base and timeouts

- Extend **`BaseIntegrationTest`** for integration tests that need a real stack. It provides:

- `stack` from **`Credentials.getStack()`** (`.env`-based).

- Timeout constants: `DEFAULT_TIMEOUT_SECONDS`, `PERFORMANCE_TIMEOUT_SECONDS`, `LARGE_DATASET_TIMEOUT_SECONDS`.

- Use **`Assertions.assertTimeout(Duration.ofSeconds(...), () -> { ... })`** (or equivalent) for async or long-running operations so tests don’t hang.

## Test data and credentials

- **Credentials:** Use **`Credentials`** and a `.env` file for integration tests (API key, delivery token, environment). Do not commit real tokens; document required env vars (e.g. in README or test docs).

- **Fixtures:** Use existing test assets (e.g. under `src/test/` or `target/test-classes/`) where applicable.

## Coverage

- **JaCoCo** is configured in `pom.xml`. Reports are generated on `mvn test` (e.g. `target/site/jacoco/`). Maintain or improve coverage when adding or changing production code; avoid removing tests that cover critical paths without replacement.