diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..82a4909 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,4 @@ +# AGENTS.md + +Follow `CLAUDE.md` for repository-specific agent instructions. + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0829ef5 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,56 @@ +# CLAUDE.md + +## Project + +Java 21 REST Assured/JUnit 5 API automation framework for Conduit-style API +coverage, contract checks, reliability evidence, and portfolio reporting. + +## Session Start + +Refresh the local code graph before structural discovery: + +`bash .agent/index-codebase-memory.sh` + +Current MCP project name: + +`home-vyaspc-Documents-Repo-aria-api-framework` + +## Commands + +- Install/use wrapper: `./gradlew --version` +- Main verification: `./gradlew test` +- Tagged tests: `./gradlew test -DincludeTags=smoke` +- Format: `./gradlew spotlessApply` +- Format check: `./gradlew spotlessCheck` +- Static checks: `./gradlew spotbugsMain spotbugsTest` +- Dependency/security artifacts: `./gradlew cyclonedxBom` + +## Layout + +- `src/main/java` - reusable API framework code, clients, config, reporting helpers. +- `src/test/java` - JUnit 5 API, contract, reliability, and seeded-defect tests. +- `src/test/resources` - test data, schemas, Allure/JUnit resources. +- `docs/` - architecture, execution, reliability, writing-tests, and debugging guides. +- `reliability/quarantine.yml` - quarantine policy and known reliability exceptions. +- `portfolio/manifest.yml` - portfolio metadata. + +## Codebase Memory MCP + +Use graph tools before broad file reads: + +1. `list_projects` +2. `get_architecture(project="home-vyaspc-Documents-Repo-aria-api-framework")` +3. `search_graph` +4. `trace_path` +5. `get_code_snippet` +6. `query_graph` + +Fall back to `rg` for literals, configs, docs, generated files, or insufficient graph results. + +## Agent Rules + +- Cite `file:line` for code claims whenever practical. +- Keep changes scoped to the framework layer under test; avoid unrelated cleanup. +- Prefer targeted Gradle tasks and tagged tests over full-suite reruns. +- Do not commit `.codebase-memory/`, `codebase-memory/`, or `.agent/index-codebase-memory.sh`. + diff --git a/README.md b/README.md index 32fd96d..615733c 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,11 @@ provider verification, OpenAPI endpoint coverage, security boundaries, redacted diagnostics, and CI quality gates. The name refers to REST API assertions and is not related to WAI-ARIA accessibility standards. +The core engineering problem this framework answers: how do you get real Pact +provider verification without depending on someone else's service? See +[ADR-005](docs/adr/ADR-005-owned-provider-http-server.md) for the owned-provider +answer, and the tech stack and project structure below for how it fits together. + ## Reviewer Proof | Evidence | Link | @@ -67,6 +72,10 @@ evidence. See [CHANGELOG.md](CHANGELOG.md). ## Run Locally +```bash +./gradlew clean test -Denv=dev +``` + ```powershell .\gradlew.bat clean test -Denv=dev ``` @@ -75,9 +84,9 @@ The default `test` task is deterministic. It excludes tests tagged `live` and ru Run a tag: -```powershell -.\gradlew.bat test -Denv=dev --tests "*AuthTests" -.\gradlew.bat smokeTest -Denv=dev +```bash +./gradlew test -Denv=dev --tests "*AuthTests" +./gradlew smokeTest -Denv=dev ``` Dedicated Gradle tasks are available for common deterministic suites: `smokeTest`, `regressionTest`, `contractTest`, `pactProviderVerificationTest`, `securityTest`, and `containerTest`. Use `test -DincludeTags=...` only when you intentionally want raw JUnit tag filtering; live tags require explicit credentials and network access. @@ -86,6 +95,12 @@ JUnit tags are available as `smoke`, `regression`, `negative`, `known-demo-api-l Run live public API tests only when credentials and network access are intentionally available: +```bash +export BOOKER_USERNAME="" +export BOOKER_PASSWORD="" +./gradlew liveTest -Denv=dev +``` + ```powershell $env:BOOKER_USERNAME="" $env:BOOKER_PASSWORD="" @@ -96,27 +111,27 @@ Scheduled CI runs `liveSmokeTest` weekly (Sunday 00:00 UTC) against the configur Run the full quality gate used by CI: -```powershell -.\gradlew.bat clean check securityScan allureReport -Denv=dev +```bash +./gradlew clean check securityScan allureReport -Denv=dev ``` Generate OpenAPI endpoint coverage: -```powershell -.\gradlew.bat openApiCoverageReport +```bash +./gradlew openApiCoverageReport ``` Generate Allure: -```powershell -.\gradlew.bat allureReport +```bash +./gradlew allureReport ``` Run with Docker: -```powershell -$env:ENV="dev" -$env:GITHUB_TOKEN="" +```bash +export ENV=dev +export GITHUB_TOKEN="" docker compose up --build ``` @@ -177,14 +192,14 @@ The metrics contract reports zero test-level retries by design. See the [reliabi Generate a local SBOM plus OSV scan instructions: -```powershell -.\gradlew.bat securityScan +```bash +./gradlew securityScan ``` If `osv-scanner` is installed, `securityScan` runs it against `build/reports/cyclonedx/bom.json` and fails on reported vulnerabilities. To fail when the scanner is missing, run: -```powershell -.\gradlew.bat securityScan -PrequireOsvScanner=true +```bash +./gradlew securityScan -PrequireOsvScanner=true ``` ## Project Structure @@ -236,21 +251,21 @@ Do not distribute `.gradle/`, `.idea/`, or `build/` as part of the portfolio sou ## Documentation -- [Portfolio Review Guide](docs/Portfolio_Review_Guide.md) +- [Portfolio Review Guide](docs/portfolio-review-guide.md) - [Current verification record](docs/evidence/latest-verification.md) - [Enterprise adaptation](docs/enterprise-adaptation.md) -- [Configuration Guide](docs/Configuration_Guide.md) -- [Execution Guide](docs/Execution_Guide.md) -- [Writing Tests](docs/Writing_Tests.md) -- [Debugging Test Failures](docs/Debugging_Test_Failures.md) -- [Dos and Don'ts](docs/Dos_And_Dont.md) +- [Configuration Guide](docs/configuration-guide.md) +- [Execution Guide](docs/execution-guide.md) +- [Writing Tests](docs/writing-tests.md) +- [Debugging Test Failures](docs/debugging-test-failures.md) +- [Dos and Don'ts](docs/dos-and-dont.md) - [Security Test Strategy](docs/SECURITY_TEST_STRATEGY.md) - [Threat Model](docs/security/aria-api-framework-threat-model.md) - [Reliability and Quarantine Policy](docs/RELIABILITY_POLICY.md) - [Failure Example and Triage](docs/failure-example.md) - [Seeded Defect Examples](docs/seeded-defects.md) - [Architecture](docs/ARCHITECTURE.md) -- [Architecture Decision Records](docs/Adr/README.md) +- [Architecture Decision Records](docs/adr/README.md) ## Repository Governance diff --git a/docs/Adr/ADR-001-deterministic-default-execution.md b/docs/adr/ADR-001-deterministic-default-execution.md similarity index 100% rename from docs/Adr/ADR-001-deterministic-default-execution.md rename to docs/adr/ADR-001-deterministic-default-execution.md diff --git a/docs/Adr/ADR-002-layered-service-client-architecture.md b/docs/adr/ADR-002-layered-service-client-architecture.md similarity index 100% rename from docs/Adr/ADR-002-layered-service-client-architecture.md rename to docs/adr/ADR-002-layered-service-client-architecture.md diff --git a/docs/Adr/ADR-003-sanitized-allure-diagnostics.md b/docs/adr/ADR-003-sanitized-allure-diagnostics.md similarity index 100% rename from docs/Adr/ADR-003-sanitized-allure-diagnostics.md rename to docs/adr/ADR-003-sanitized-allure-diagnostics.md diff --git a/docs/Adr/ADR-004-contract-openapi-quality-gates.md b/docs/adr/ADR-004-contract-openapi-quality-gates.md similarity index 100% rename from docs/Adr/ADR-004-contract-openapi-quality-gates.md rename to docs/adr/ADR-004-contract-openapi-quality-gates.md diff --git a/docs/Adr/ADR-005-owned-provider-http-server.md b/docs/adr/ADR-005-owned-provider-http-server.md similarity index 100% rename from docs/Adr/ADR-005-owned-provider-http-server.md rename to docs/adr/ADR-005-owned-provider-http-server.md diff --git a/docs/Adr/README.md b/docs/adr/README.md similarity index 100% rename from docs/Adr/README.md rename to docs/adr/README.md diff --git a/docs/Configuration_Guide.md b/docs/configuration-guide.md similarity index 100% rename from docs/Configuration_Guide.md rename to docs/configuration-guide.md diff --git a/docs/Debugging_Test_Failures.md b/docs/debugging-test-failures.md similarity index 100% rename from docs/Debugging_Test_Failures.md rename to docs/debugging-test-failures.md diff --git a/docs/Dos_And_Dont.md b/docs/dos-and-dont.md similarity index 100% rename from docs/Dos_And_Dont.md rename to docs/dos-and-dont.md diff --git a/docs/evidence/latest-verification.md b/docs/evidence/latest-verification.md index 4e9590b..1ddc66c 100644 --- a/docs/evidence/latest-verification.md +++ b/docs/evidence/latest-verification.md @@ -10,7 +10,7 @@ | Evidence class | Controlled and scheduled-live | | Result counts | 66 tests, 66 passed, 0 failed, 0 errors, 0 skipped (13.695s), from JUnit XML | | Report | [Allure report](https://qa-test-automation-frameworks.github.io/aria-api-framework/) | -| Known limitations | [Known issues](../known-issues.md) and [review guide](../Portfolio_Review_Guide.md) | +| Known limitations | [Known issues](../known-issues.md) and [review guide](../portfolio-review-guide.md) | The machine-readable record with the exact SHA, run ID/URL, conclusion, and result counts is published at [`latest-verification.json`](latest-verification.json). This diff --git a/docs/Execution_Guide.md b/docs/execution-guide.md similarity index 100% rename from docs/Execution_Guide.md rename to docs/execution-guide.md diff --git a/docs/Portfolio_Review_Guide.md b/docs/portfolio-review-guide.md similarity index 97% rename from docs/Portfolio_Review_Guide.md rename to docs/portfolio-review-guide.md index 1e3334a..ca3f83d 100644 --- a/docs/Portfolio_Review_Guide.md +++ b/docs/portfolio-review-guide.md @@ -4,7 +4,7 @@ This guide is a short evidence-based path through the repository. Claims below l ## Recommended Review Order -1. Read the [architecture](ARCHITECTURE.md) and [ADR index](Adr/README.md). +1. Read the [architecture](ARCHITECTURE.md) and [ADR index](adr/README.md). 2. Inspect [`BaseApiClient`](../src/main/java/com/aria/framework/clients/BaseApiClient.java), services, and typed request/response models. 3. Review [`RedactionPolicy`](../src/main/java/com/aria/framework/reporting/RedactionPolicy.java) and the [threat model](security/aria-api-framework-threat-model.md). 4. Read the owned fixture and atomic concurrency test under [`src/test`](../src/test/java/com/aria/framework/). diff --git a/docs/Writing_Tests.md b/docs/writing-tests.md similarity index 100% rename from docs/Writing_Tests.md rename to docs/writing-tests.md