# build-tests — Test generator

> **Builds:** PHPUnit feature tests for a feature's API endpoints and/or admin CRUD, in base conventions.
> **Runs AFTER** [`build-api.md`](build-api.md) / [`build-dashboard-crud.md`](build-dashboard-crud.md),
> **before** the Definition-of-Done gate in [`verify.md`](verify.md). Tests are part of "done" — not optional.
> **Inputs:** the per-API plan (`docs/project/api/<audience>/<flow>/<endpoint>.md`), the models/factories from
> [`build-database.md`](build-database.md), and base's response envelope (`app/Traits/Response`).

---

## 0) Why
A base that spawns many projects must ship **working** features. Tests catch the failures the manual
dry-run caught by hand (dead endpoints, wrong envelope, broken seeders, missing auth) — automatically,
every time, in the DoD gate.

## 1) What to generate

**Per API endpoint:**
- **Success path** → correct payload returns the right status (200/201) and the **exact** envelope
  (`message` + `data`, or `data` + `pagination` for lists) — assert keys, not ad-hoc shapes.
- **Validation failure** → invalid payload returns **422** with `{message, errors}`.
- **Auth** → protected endpoint without a Sanctum token → **401**; with a valid token → success.
- **i18n** → `?lang=ar` vs `?lang=en` returns the localized `message` (assert the Arabic string for `ar`).
- **Pagination** → list endpoints return the standard pagination keys (`current_page`, `per_page`,
  `total`, `last_page`, `from`, `to`).

**Per admin CRUD:**
- store / update / destroy / restore happy paths; validation failures; `auth:admin` guard (guest → redirect/401).

## 2) Conventions (match the base exactly)
- Location: `tests/Feature/Api/<Feature>/...` and `tests/Feature/Admin/<Entity>/...`.
- Use `RefreshDatabase` + the model **factories** (build-database must provide them — if a factory is
  missing, that's a build-database gap to fix first).
- Seed required reference data (e.g. countries) via the project seeders or factory relations.
- Assert against the canonical envelope from `app/Traits/Response/*` (success/fail/validation/pagination),
  never a hand-written shape.
- Authenticate with `Sanctum::actingAs($user)` for protected routes; admin tests use the `admin` guard.

## 3) Verify (definition of done)
- `php artisan test --filter=<Feature>` green.
- Covered: success + validation + auth + i18n + pagination for every endpoint; CRUD actions for every admin entity.
- Feeds the full DoD gate in [`verify.md`](verify.md).

## References (single source — do not duplicate)
- Endpoint spec → [`build-api.md`](build-api.md) · CRUD → [`build-dashboard-crud.md`](build-dashboard-crud.md)
- Factories/models → [`build-database.md`](build-database.md) · DoD gate → [`verify.md`](verify.md)