# Backend API Scenarios

This directory is the planned home for backend/API scenario validation.

The current repository already has backend unit tests, backend e2e tests, and a
root runtime smoke command. Use those first before adding a dedicated scenario
helper.

## Current Supported Checks

Run backend checks from the workspace root:

```sh
yarn workspace backend test
yarn workspace backend test:e2e
yarn smoke:runtime
```

Use `yarn workspace backend test` for resolver, service, controller, and helper
logic that can be tested without real HTTP or database boundaries.

Use `yarn workspace backend test:e2e` when a backend change crosses GraphQL/API,
Nest module, auth, Prisma, or database boundaries. Current e2e coverage includes:

- `/` backend bootstrap response.
- `/health` response.
- GraphQL `health`.
- GraphQL user creation and user listing.
- GraphQL login and authenticated `currentUser`.
- Cleanup of generated `e2e-` users.

Use `yarn smoke:runtime` when the change needs the real local dev app path,
including backend boot, frontend boot, GraphQL requests, auth flow, and smoke-user
cleanup.

## Scenario Structure

When a future chunk adds dedicated backend/API scenarios, prefer files such as:

```text
apps/backend/scenarios/auth-admin-bootstrap.scenario.md
apps/backend/scenarios/graphql-contract.scenario.md
```

Each scenario should state:

- purpose and risk covered.
- exact command to run.
- required local-only environment.
- test data prefixes.
- records created.
- cleanup command or automatic cleanup behavior.
- expected API/schema outputs.
- failure interpretation.

## Fixture And Data Safety

- Do not use production credentials.
- Do not point scenario checks at production databases.
- Use deterministic test prefixes such as `e2e-`, `smoke-`, or `scenario-`.
- Clean up created users and records during the test or immediately after it.
- Never delete non-prefixed users or broad production-like data.
- Do not print access tokens, JWT secrets, database URLs, or environment values.

## Validation Selection

Choose the narrowest useful layer:

- Unit tests: service/resolver/controller logic, validation, and error mapping.
- E2E/API tests: GraphQL schema behavior, auth guards/current user, Prisma-backed
  reads/writes, and module wiring.
- Scenario/smoke tests: bootstrap assumptions, admin/user setup, cross-feature
  backend flows, and regression-sensitive sequences.
- Runtime smoke: real local backend/frontend integration and dev-server behavior.

## High-Priority Scenario Target

The next full requirements-to-orchestration test should cover auth/admin
bootstrap assumptions:

- whether an admin user exists or must be created.
- how admin setup is safely seeded locally.
- login/currentUser behavior for admin and standard users.
- cleanup expectations for generated scenario users.
- GraphQL/API contract checks for the bootstrap path.