> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/platform/platform-services/approval-workflow-engine/testing.md).

# Testing

All tests are **hermetic** — no Docker, no Postgres, no Keycloak, no network. The test suite drops the SQLAlchemy schema onto an in-memory SQLite database via `aiosqlite`, points dev-mode auth at empty issuer (unsigned JWTs accepted), and exercises the full FastAPI app over an in-process ASGI transport. The whole suite runs in about a second.

## Run

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e '.[test]'
pytest -v
```

## What's covered

### `test_health.py` — service endpoints

Verifies `/v1/awe/health`, `/v1/awe/version`, `/v1/awe/config` return the documented envelopes and that `/config` does **not** leak Keycloak secrets.

### `test_policies.py` — policy CRUD + lifecycle

* Create a draft, list, list versions, fetch version detail.
* Activate a draft → status flips to `active`.
* Simulate: resolves approvers for a sample context, returns the same stages the policy declares.
* AuthZ: unauthenticated calls get 401; non-admin tokens get 403.
* Edit: draft versions can be edited in place (`PATCH`); active and archived versions return `409 AWE-007`.

### `test_requests_and_tasks.py` — end-to-end approval lifecycle

* **Two-stage happy path**: create policy → create request → alice approves stage 1 (`any-1`) → bob's task flips to `skipped` → director approves stage 2 (`all` with 1 approver) → request transitions to `approved`. Verifies event timeline contains `request_created`, `stage_started`, `stage_completed`, `request_approved`.
* **Reject path**: both approvers reject a single stage → request ends `rejected`.
* **Cancel**: admin cancels an in-flight request; outstanding tasks flip to `skipped`.
* **Idempotency**: retrying `POST /requests` with the same `Idempotency-Key` returns the same `request_id` without creating a second request row.
* **Search**: filter by `artifact_type` / `artifact_id`.

### `test_webhook_signing.py` — HMAC signing contract

* Signature equals `"sha256=" + HMAC_SHA256(secret, timestamp + "." + body)`.
* Two signatures with different timestamps differ for the same body — proves replay-safety.

### `test_sla_monitor.py` — SLA expiry

* A task with `due_at` in the past is flipped to `expired` by one tick of the SLA monitor.
* A `task_expired` event is appended to the request timeline with `task_id`, `stage_order`, `assignee`, and `due_at` in the payload.
* A `webhook_delivery` row is enqueued `pending` pointing at the request's `callback_url`.
* The noop path (no due tasks) is exercised to confirm the monitor commits cleanly.

## Sample payloads

Sample policy payload used across tests:

```json
{
  "policy_key": "registry.cr.v1",
  "name": "Registry CR approval",
  "artifact_type": "registry.change_request",
  "stages": [
    {
      "name": "District officers",
      "stage_order": 1,
      "mode": "any-n",
      "mode_value": 1,
      "rules": [
        {"rule_type": "user", "rule_value": {"user_id": "u-officer-A"}},
        {"rule_type": "user", "rule_value": {"user_id": "u-officer-B"}}
      ]
    },
    {
      "name": "State directors",
      "stage_order": 2,
      "mode": "all",
      "rules": [
        {"rule_type": "user", "rule_value": {"user_id": "u-director-X"}},
        {"rule_type": "user", "rule_value": {"user_id": "u-director-Y"}}
      ]
    }
  ]
}
```

Re-usable as `curl -d @policy.json` against a running dev-mode instance.

## Running against real Postgres (optional)

The production code path uses async Postgres via `asyncpg`. To exercise it locally:

```bash
docker compose up postgres -d
DATABASE_URL='postgresql+asyncpg://postgres:postgres@localhost:5432/awe' \
  pytest -v
```

The schema is ensured at startup via `Base.metadata.create_all`, so no migrations needed. This catches Postgres-specific oddities (SKIP LOCKED, JSONB coercion) that SQLite happily accepts.

## Testing webhook delivery

The dispatcher and SLA monitor loops run as `asyncio.Task`s during lifespan. In the smoke tests they're started but never tick (they sleep on their poll interval). To exercise delivery specifically:

```python
# point callback_url at a local capture, e.g. via `nc -l 9999` or a
# FastAPI stub; set webhook.poll_interval_seconds=1 in config; watch
# webhook_delivery.status flip to `delivered` after a few seconds.
```

A dedicated integration test for this path can be added later.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.openg2p.org/platform/platform-services/approval-workflow-engine/testing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.