ai-context-engineering-for-qa: Skill for Claude Code

Recommended Flow

Main pipeline: /repo-scout → /api-test-cases → /api-tests.

For single-endpoint deep-dive: /spec-audit → /api-isolated-tests → /api-tests.

Running directly on a specification also works — the skill will generate tests without a scenario matrix, but traceability @Link annotations will reference the spec instead of scenario IDs.

---

🔒 SYSTEM REQUIREMENTS

Before execution the agent MUST load: .claude/protocols/gardener.md

---

SDET: API Automation (Kotlin)

When to Use

• There is audit/test-scenarios.md with a scenario matrix — cover them with automated tests
• Need to write tests for a new endpoint from scratch
• Review existing tests for standards compliance (review arg)

Input Context (Process Isolation)

context: fork — you cannot see chat history before your invocation.

Allowed inputs: audit/test-scenarios.md, specification, CLAUDE.md, build.gradle.kts, existing src/ (style reference only). Forbidden: Assumptions from "previous agent context", inventing endpoint contracts.

Protocol

1. Stack: Locked in CLAUDE.md → Tech Stack. Kotlin-specific additions: Ktor HttpClient(CIO) via by lazy(LazyThreadSafetyMode.SYNCHRONIZED), Awaitility (seconds only), Faker (TestData generators), JSON Schema Validator.
2. BANNED: Thread.sleep, delay, runBlocking (use runTest), HttpClient( in *Tests.kt (inline HTTP in tests), manual @AllureId, shouldBe (use assertEquals), assert( (Kotlin builtin — use assertEquals/assertTrue from org.junit.jupiter.api.Assertions), LocalDateTime.now() in strict assertions. Zero-comment policy: // and /* */ in generated code are FORBIDDEN. 2a. Coroutine Tests: Preferred: fun test(): Unit = runTest { } from kotlinx-coroutines-test. If runBlocking is unavoidable — explicit return type required: fun test(): Unit = runBlocking { }. FORBIDDEN: delay() as timing substitute — use Awaitility. 2b. Test Lifecycle: @BeforeEach/@AfterEach for setup/teardown. lateinit var for resources requiring cleanup. FORBIDDEN: @TestInstance(PER_CLASS) with field initialization — JUnit skips class init on constructor failure. 2c. DRY API Clients: FORBIDDEN: duplicating client method bodies to return different response types (e.g., registerUser(): RegisterResponse + registerUserExpectError(): ErrorResponse with identical request construction). Generate a single method returning HttpResponse or a generic suspend inline fun <reified T> request(...) and let the test parse the body as needed. (ref: api/dry-api-client.md) 2d. Fail Fast in Test Clients: FORBIDDEN: wrapping API client HTTP calls or JSON deserialization in try/catch blocks that return empty stub objects (catch (e: Exception) { return RegisterResponse() }). Exceptions MUST propagate so the test runner reports the infrastructure failure at the point of failure, not on a later assertion. (ref: api/silent-catch.md) 2e. Ktor Body Extraction Rule: FORBIDDEN: response.toString() to obtain response body — in Ktor this returns object metadata, not the body. Use response.body<T>() (typed, via ContentNegotiation plugin) or response.bodyAsText() if raw string is required. Manual Json.decodeFromString(response.toString()) is a guaranteed runtime crash. (ref: api/ktor-body-extraction.md) 2f. Single Serialization Framework Rule: Use exactly one JSON framework across the entire generation — either Jackson OR kotlinx.serialization. FORBIDDEN: mixing Jackson annotations (@JsonProperty, @JsonNaming, @JsonIgnoreProperties) with kotlinx.serialization parsing (Json.decodeFromString, @Serializable). If using Ktor with ContentNegotiation(jackson()), deserialize via response.body<T>() — never parse raw strings manually. If the stack is jackson, all DTOs use @JsonNaming/@JsonProperty. If the stack is kotlinx.serialization, all DTOs use @Serializable and no Jackson annotations appear anywhere. 2g. Time-Dependent Scenarios (TTL/Cache): FORBIDDEN: Using Thread.sleep or delay() to simulate time passing for cache expiration, idempotency TTLs, or rate limits. Do not blindly execute sequential requests expecting time to advance instantly. For short asynchronous state changes, use Awaitility. For long temporal conditions (e.g., 5-minute cache expiration), if the specification does NOT explicitly provide a testability hook (e.g., X-Test-Advance-Time header or cache invalidation endpoint), you MUST generate the complete test logic and annotate the test method with @Disabled("Time-dependent scenario: {Wait Time}. Requires testability hook (time-travel/cache-clear) or manual execution."). 2h. Timestamp Response Validation: If the specification defines a time-based response field (e.g., expires_at = request_time + N minutes, JWT exp claim), the test MUST validate it with a relative drift check: assertTrue(abs(actual - expected) < driftToleranceSeconds, "timestamp drift"). Using Instant.now() + offset is acceptable; using isNotBlank() or > 0 alone is INSUFFICIENT. FORBIDDEN: LocalDateTime.now() in assertions. 2i. WireMock Integration for External Services: When a test configures WireMock stubs for external services (SMS gateway, payment provider, etc.), the test MUST connect the mock to the application under test. At minimum: set a system property or environment variable (e.g., System.setProperty("SMS_GATEWAY_URL", "http://localhost:${wireMockServer.port()}")) in @BeforeEach and clear it in @AfterEach. A disconnected WireMock server (started but not referenced by the app) is a SILENT TEST BUG — the test passes/fails based on real service state, not mock behavior. 2k. Eventual Consistency Writes: If repo-scout-report §12 marks a write→read pair as "Eventual", FORBIDDEN to assert the read immediately after write. Use Awaitility polling with bounded timeout. (ref: api/eventual-consistency-writes.md) 2l. Batch Partial Failure: If repo-scout-report §12 lists batch operations, include a mixed valid+invalid input case to verify error propagation strategy (atomic rollback vs partial 207 Multi-Status). Testing only all-valid and all-invalid is INSUFFICIENT. (ref: api/batch-partial-failure.md) 2j. Configurable BASE_URL: Use a computed property so any CI/CD environment can override the target server without recompilation: val BASE_URL: String get() = System.getProperty("BASE_URL", "http://localhost:8080"). If ConnectException appears in Smoke Run and no live server is available → run /api-mocks to generate an in-process mock, then re-run. TLS-enforcement tests cannot pass with an HTTP mock — acceptable as documented infra limitation. 2m. TLS/HTTPS Enforcement Tests: FORBIDDEN: generating a test that replaces https:// with http:// and asserts a 4xx rejection — when both URLs hit the same HTTP-only mock, the test structurally passes regardless of TLS state (silent false-positive). If a scenario requires verifying TLS enforcement and no HTTPS infrastructure exists: generate the test skeleton, immediately annotate @Disabled("TLS enforcement: requires HTTPS-capable server or WireMock HTTPS mode. HTTP mock cannot simulate certificate/protocol rejection."), and add a code comment explaining the correct infrastructure requirement. Do NOT generate a functionally broken test. 2n. HTTP Client Timeout (Mandatory): Every HttpClient instantiation MUST include: install(HttpTimeout) { requestTimeoutMillis = 30_000L; connectTimeoutMillis = 10_000L; socketTimeoutMillis = 30_000L }. Tests without timeout configuration hang indefinitely on infrastructure failures and block CI pipelines.
3. Security Headers Rule: Every positive test (POST/PUT/DELETE with 2xx) MUST verify Content-Type, X-Content-Type-Options, Strict-Transport-Security via assertEquals on response.headers. (ref: api/missing-security-headers.md)
4. Structure:
   • requests/: DTOs + Request/Response objects. ALL data classes mapped to snake_case JSON (request AND response) — apply @JsonNaming(SnakeCaseStrategy::class) on all DTOs — omitting it on response DTOs causes silent null fields. Also add @JsonIgnoreProperties(ignoreUnknown = true).
   • helpers/: @Step annotated flows.
   • tests/: @Epic (from feature/package name), @Feature (from endpoint name), @Severity, @DisplayName. @AllureId — NOT generated: assigned manually or via utility after TMS binding. MANDATORY TAGS: Analyze business logic — add @Tag("CRITICAL") + @Severity(SeverityLevel.CRITICAL) for Money flows, Security/Auth, or Data integrity endpoints; add @Tag("REGRESSION") for all others.
   • External Integrations: If the endpoint under test calls 3rd-party services (payments, SMS, email providers), configure a WireMock stub in @BeforeEach so the test does not make real HTTP calls to external domains.
5. Gates: compileTestKotlin, ktlintCheck.