# Vehicles Positive Flow Tests

**Task**: AZ-577_test_vehicles_positive
**Name**: Vehicles positive tests (FT-P-01..06)
**Description**: Implement xUnit blackbox tests for the 6 happy-path Vehicle CRUD scenarios — create non-default, create default (demotes prior), setDefault, list (no-pagination + Name ASC), filter (case-INSENSITIVE name + exact isDefault), delete with no references.
**Complexity**: 5 points
**Dependencies**: AZ-576_test_infrastructure
**Component**: Blackbox Tests
**Tracker**: AZ-577
**Epic**: AZ-575

## Problem

The `/vehicles` surface implements two non-obvious invariants that documentation alone cannot guarantee: (1) creating a default vehicle clears any prior default in the same logical step, and (2) the list filter is case-INSENSITIVE on `name` (the docs said case-sensitive until 2026-05-14 — drift now corrected, but only an executable test can pin the actual code path). Without these tests, a future refactor of `VehicleService` could silently re-introduce two default rows or a case-sensitive filter and break consumers (`autopilot` reads the default vehicle on boot).

## Outcome

- All six FT-P-01..06 scenarios run against the dockerised `missions` service via HTTP + Npgsql side-channel and pass.
- Each test produces a CSV row with `Category=Blackbox`, `Traces=AC-1.x`, `Result=pass`, and an `ExecutionTimeMs` under the documented `Max execution time` (5s for create paths, 2s for read/delete).
- The list test asserts both shape (`array` not `PaginatedResponse`) and ordering (`Name ASC`).
- The filter test asserts case-INSENSITIVE matching for two casings (`BR` and `br`).
- The default-clear invariant is verified via DB count (`is_default=true` count == 1 after every default-creating action).

## Scope

### Included

- FT-P-01 Create non-default — `POST /vehicles` body shape + PascalCase response + DB row count.
- FT-P-02 Create default demotes prior default — `seed_one_default_vehicle` precondition; assert exactly one default after.
- FT-P-03 setDefault promotes existing vehicle — `POST /vehicles/{id}/setDefault`; assert clear-then-set via side-channel.
- FT-P-04 List unpaginated + Name ASC — assert body is JSON array (not `{Items,Page,…}`), assert length and ordering.
- FT-P-05 Filter `name=BR&isDefault=true` then `name=br&…` — assert case-INSENSITIVE substring match against `seed_3_vehicles_2_default`.
- FT-P-06 Delete with no references — `204` + DB count 0.

### Excluded

- FT-N-03 "delete vehicle in use returns 409" lives in Task 13 (negative tests).
- Validation-of-input scenarios (empty `Name`, negative `BatteryCapacity`, unknown `Type` int) are carry-forwards documented in `test-data.md` § Data Validation Rules; they are NOT tested here because the spec marks them as "accepted today" — they belong to the Refactor Backlog, not this task.
- TOCTOU race on default-vehicle exclusivity (NFT-RES-08) lives in Task 17.

## Acceptance Criteria

**AC-1: FT-P-01 returns 201 with PascalCase body**
Given `seed_empty` and a JWT with `permissions=FL`
When `POST /vehicles` is issued with the documented body
Then response is `201 Created`, body parses as `Vehicle` with PascalCase keys, `Id` parses as UUID, side-channel `SELECT COUNT(*) FROM vehicles WHERE id=<returned>` returns 1

**AC-2: FT-P-02 demotes prior default**
Given `seed_one_default_vehicle` (prior row `P1.is_default=true`)
When `POST /vehicles { …, IsDefault:true }` is issued
Then response is `201`, side-channel shows new row `is_default=true`, row `P1.is_default=false`, and `SELECT COUNT(*) WHERE is_default=true` == 1

**AC-3: FT-P-03 setDefault clears prior**
Given `seed_one_default_vehicle` plus a non-default row `P2`
When `POST /vehicles/{P2}/setDefault { IsDefault:true }` is issued
Then response is `200` with `Id==P2, IsDefault==true`, and side-channel shows `P2.is_default=true`, `P1.is_default=false`, count==1

**AC-4: FT-P-04 list is unpaginated and ordered**
Given `seed_3_vehicles_2_default` containing `BR-01, BR-02, MQ-9` in any insert order
When `GET /vehicles` is issued
Then response is `200`, body parses as a JSON array (NOT an object with `Items`), `body.length == 3`, and `[v.Name for v in body] == ["BR-01","BR-02","MQ-9"]`

**AC-5: FT-P-05 filter is case-INSENSITIVE**
Given `seed_3_vehicles_2_default`
When `GET /vehicles?name=BR&isDefault=true` AND `GET /vehicles?name=br&isDefault=true` are issued
Then both responses are `200` with `body.length == 1` and `body[0].Name == "BR-01"`

**AC-6: FT-P-06 delete is 204 + row gone**
Given one vehicle row with no missions referencing it
When `DELETE /vehicles/{id}` is issued
Then response is `204 No Content` with empty body, and side-channel shows `count == 0` for that id

## Non-Functional Requirements

**Performance**
- Each test must complete inside the documented `Max execution time` from `blackbox-tests.md` (5s for FT-P-01..03, 5s for FT-P-07-style writes, 2s for FT-P-04..06). The xUnit `[Trait("max_ms", "5000")]` or per-test `Timeout` must reflect this.

**Reliability**
- Tests share a `[Collection("Vehicles")]` xUnit collection and use `IClassFixture<DbResetFixture>` to TRUNCATE between scenarios. No state must leak between FT-P-01 and FT-P-04.

## Blackbox Tests

| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|------------------------|-------------|-------------------|----------------|
| AC-1 | `seed_empty`, JWT permissions=FL | `POST /vehicles` non-default body | `201` + PascalCase `Vehicle` + DB count 1 | — |
| AC-2 | `seed_one_default_vehicle` (P1) | `POST /vehicles { IsDefault:true }` | `201` + DB shows count==1 default after | AC-1.2 invariant |
| AC-3 | `seed_one_default_vehicle` + extra P2 | `POST /vehicles/{P2}/setDefault` | `200` + DB count==1 default; P1 cleared | AC-1.2 / AC-1.4 |
| AC-4 | `seed_3_vehicles_2_default` (`BR-01,BR-02,MQ-9`) | `GET /vehicles` shape + order | `200` + array + Name ASC | AC-1.5 |
| AC-5 | `seed_3_vehicles_2_default` | `GET /vehicles?name=BR…` + `?name=br…` | `200` + len 1 + `BR-01` for both casings | AC-1.6 |
| AC-6 | One row, zero missions | `DELETE /vehicles/{id}` | `204` + DB count 0 | AC-1.10 |

## Constraints

- HTTP only against `http://missions:8080` (no project reference to `Azaion.Missions.csproj`).
- Bearer token minted via `https://jwks-mock:8443/sign` with `permissions=FL`.
- DB assertions through the Npgsql side-channel only; marked `[Trait("db_access","seed-or-assert-only")]`.
- AAA pattern with `// Arrange` / `// Act` / `// Assert` comments per `coderule.mdc`.
- PascalCase JSON contract (`PropertyNamingPolicy = null`) is part of the SUT contract; the test must NOT silently accept camelCase.

## Risks & Mitigation

**Risk 1: Tests depend on side-channel SQL that drifts from the SUT migrator**
- *Risk*: If the migrator changes the `vehicles` column set, hand-rolled `INSERT` in the seed fixture breaks.
- *Mitigation*: Seed fixtures use the schema produced by the SUT's own startup migrator — `docker compose up` runs first, then the fixture inserts into the already-migrated tables.

**Risk 2: Ordering test (AC-4) is flaky if insert order accidentally matches alphabetic order**
- *Risk*: A non-deterministic seed insert could mask a missing `OrderBy`.
- *Mitigation*: Seed fixture inserts rows in `[MQ-9, BR-02, BR-01]` order (reverse alphabetic) so the test fails if the SUT omits the `OrderBy(a => a.Name)`.

## System Under Test Boundary

- Tests drive the product through the public HTTP surface (`http://missions:8080/vehicles*`) plus the documented DB side-channel for fixture seeding and post-call assertions; expected outputs are compared against `_docs/00_problem/input_data/expected_results/results_report.md` rows AC-1 1.1, 1.2, 1.4, 1.5, 1.6, 1.10.
- Stubs are allowed ONLY for the external `admin` JWT issuer (the `jwks-mock` container per `tests/Azaion.Missions.JwksMock/`).
- Stubs, fakes, monkeypatches, deterministic fallbacks, or direct imports are NOT allowed for any internal product module — including `VehicleService`, `VehiclesController`, `AppDataConnection`, `DatabaseMigrator`, `JwtExtensions`, or `ErrorHandlingMiddleware`. If any of these is not implemented (e.g., the SUT image hasn't been built), the test MUST fail/block as missing product implementation — it must not pass by replacing the module with a test stub.