FactoryShield API — Postman/Newman Test Suite

This repo is a working copy of the FactoryShield Laravel API (a factory incident-reporting backend), with a full Postman/Newman API testing suite built on top of it. The Laravel app itself is unmodified in its core domain logic — everything in postman-testing/ plus a small set of supporting fixes (below) is the work this repo adds.

What's in postman-testing/

• 19-request Postman collection (collections/factoryshield-api.postman_collection.json), spec-linked to the app's own openapi.json, covering all 19 documented endpoints across 7 folders (Health, Reporter Entry, Evidence, Incidents, Reporter Incidents, Funnel Events, Governance).
• A separate Auth Bootstrap collection for minting Passport OAuth2 tokens locally (password grant), since the main app doesn't document this flow itself.
• Request chaining — evidence IDs, capability tokens, and incident IDs/references captured from one response and threaded automatically into the next request, so the 5 P0 (highest-priority) endpoints run end-to-end as a single realistic flow: submit evidence → store its content → validate it → submit an incident → reveal its reporter identity.
• Idempotency-key handling — a shared pre-request script keeps header-level and body-level idempotency keys in sync across runs.
• Full documentation in postman-testing/docs/:
  • TEST-PRIORITY.md / TEST-CASES.md — the P0/P1/P2 prioritization and the full test-case matrix for all 19 endpoints.
  • LIVING-DOCUMENTATION.md — an append-only build log of every fix, root-cause investigation, and test run this session, in chronological order.
  • MCP-QUIRKS.md — confirmed quirks of the Postman MCP connector used to build this collection (a few write-reliability gotchas worth knowing before editing it further).
  • CONVENTIONS.md — naming conventions for collections, folders, and variables.

Current status: 5/5 P0 endpoints passing

All 5 highest-priority endpoints (Initiate Evidence Upload, Store Evidence Content, Complete Evidence Upload, Submit Incident, Reveal Identity) pass their full happy-path assertions end-to-end, chained in a single run. Getting there surfaced and fixed several real, non-obvious bugs along the way — see LIVING-DOCUMENTATION.md for the full trail, including:

• A DB connection timezone bug (config/database.php) that made freshly-issued evidence capability tokens appear pre-expired.
• Two P0 endpoints (POST /api/v1/reporter/evidence/uploads, POST /api/v1/incidents) that had no auth-guard middleware at all, so entryMode: AUTHENTICATED could never succeed — fixed with a new optional/attempt-only auth middleware (app/Http/Middleware/AttemptAuthenticateApi.php) that doesn't break the existing anonymous path.
• Several self-contradictory or invalid example request bodies, each root-caused against the actual Laravel FormRequest validation rules rather than guessed at.

Running the tests locally

# 1. Set up the Laravel app as usual (composer install, .env, migrate, php artisan serve)

# 2. Copy the environment template and fill in real local values
cp postman-testing/environments/local.template.json postman-testing/environments/local.json
# edit local.json: base_url/baseUrl, a Passport password-grant client (php artisan passport:client --password),
# and a local test user's credentials

# 3. Seed the entry-policy fixture the P0 flows require (see postman-testing/test-data/)
php artisan tinker --execute="DB::unprepared(file_get_contents('postman-testing/test-data/seed-entry-policies.sql'));"

# 4. Install Newman (kept separate from the app's own package.json)
cd postman-testing/ci && npm install && cd ../..

# 5. Run it
bash postman-testing/ci/local-run.sh

local.json is gitignored (it holds real credentials/tokens) — only local.template.json is tracked.

About the underlying app

FactoryShield is a Laravel 13 / PHP 8.4 REST API (RFC 9457 problem-details error responses) for factory incident reporting — evidence upload, incident submission, reporter identity protection, and governance/audit endpoints. See openapi.json at the repo root for the full API spec. The original app repo is Abir105BS/FactoryShield-backend; this fork's focus is the testing suite and the fixes needed to make its P0 flows actually pass end-to-end.