How to test the application

1. Bring the environment up

The whole stack runs under Docker Compose: Nginx, PHP-FPM, Postgres, Redis, a queue worker, a scheduler, Mailpit for mail and MinIO for object storage.

cp .env.example .env
docker compose up -d --build
docker compose exec php php artisan key:generate
docker compose exec php php artisan migrate
npm install && npm run build

Or the shorthands in the Makefile: make up, make migrate, make ps, make logs, make build-assets.

Service	URL	Use it to
Application	http://facilities-manager.localhost	Everything below
Health check	/health	Confirm the app booted before testing anything else
Mailpit	http://localhost:8025	Read notification and invitation emails
MinIO console	http://localhost:9003	Verify uploaded photos, documents and exports landed

2. Seed a demo tenant

No admin user or sample data ships by default — credentials are never committed. Run this once against the running stack. It builds one full location branch from portfolio down to a room, an asset in that room, and your login.

docker compose exec php php artisan tinker --execute="
\$org = App\Models\Organization::factory()->create(['name' => 'Demo Org']);
\$admin = App\Models\User::factory()->create([
    'name' => 'Demo Admin',
    'email' => 'demo@facilities-manager.localhost',
    'password' => 'demo-password-123',
    'is_admin' => true,
]);
App\Models\Membership::factory()->for(\$admin)->for(\$org)->create();

\$portfolio = App\Models\Portfolio::factory()->for(\$org)->create(['name' => 'EMEA Portfolio']);
\$continent = App\Models\Continent::factory()->create(['portfolio_id' => \$portfolio->id]);
\$country = App\Models\Country::factory()->create(['continent_id' => \$continent->id]);
\$city = App\Models\City::factory()->create(['country_id' => \$country->id]);
\$facility = App\Models\Facility::factory()->create(['city_id' => \$city->id]);
\$building = App\Models\Building::factory()->create(['facility_id' => \$facility->id]);
\$floor = App\Models\Floor::factory()->create(['building_id' => \$building->id]);
\$room = App\Models\Room::factory()->create(['floor_id' => \$floor->id, 'name' => 'Room 301', 'kind' => 'room']);

\$category = App\Models\AssetCategory::factory()->create(['organization_id' => \$org->id]);
\$asset = App\Models\Asset::factory()->create([
    'organization_id' => \$org->id,
    'location_node_id' => \$room->locationNode()->firstOrFail()->id,
    'asset_category_id' => \$category->id,
    'name' => 'Rooftop AHU Unit 1',
]);

echo 'Login: '.\$admin->email.' / demo-password-123'.PHP_EOL;
"

Sign in at /operations/login with the printed credentials. Requesters, technicians and inspectors all use this same login; what differs is the permissions on their role and which surface they are sent to.

3. Run the automated suite

Before any manual session, prove the build is green. The suite covers the domain actions, the policies, the API contract and cross-tenant isolation.

make test                                   # full PHPUnit suite
docker compose exec php php artisan test --filter=WorkOrder
docker compose exec php php artisan test tests/Feature/ConvertServiceRequestToWorkOrderTest.php

make pint-check                             # PHP code style
make phpstan                                # static analysis
npm run lint                                # JavaScript and Vue
make lint-all                               # style + static analysis + tests

During development, run the checks against only the files you changed. Before a UAT deployment, run the whole thing.

4. Deployment smoke checks

Five minutes of checks that catch most bad deploys before a tester finds them:

1. curl http://facilities-manager.localhost/health returns {"status":"ok"}.
2. The marketing home page renders with styling and its navigation links resolve.
3. /operations/login renders and a seeded user can sign in.
4. The dashboard, an asset list and a work-order list all load without a 500.
5. make artisan cmd="migrate:status" shows no pending migrations.
6. make artisan cmd="queue:monitor" or the queue container's logs show a worker consuming jobs — uploads, exports and reminders depend on it.
7. Upload one photo and confirm it appears in the MinIO console.
8. Trigger one notification and confirm it lands in Mailpit.

5. UAT scenarios

Walk these in order — each one leaves the data the next one needs. Read the data-flow page alongside them if you want to know why each step lands where it does.

6. Negative and security checks

A UAT that only tests the happy path proves very little. Run at least these:

• Cross-tenant isolation — seed a second organization, then try to open its asset, work order or request by ID as a user of the first. Expect a 404 or 403, never data.
• Location scope — give a user a grant on one facility only and confirm work at another facility is invisible and un-actionable.
• Permissions — a technician must not be able to approve their own completion; a requester must not reach the operations panel.
• Lifecycle guards — converting a rejected request, completing an unassigned work order or approving one that is not completed must all be refused.
• Rate limits — repeated failed logins, searches, uploads and exports are throttled.
• Multi-factor — enrol an authenticator app from the profile page and confirm the code is required at the next sign-in, and that a recovery code works once.
• Audit trail — after the session, export the audit trail and confirm every participant's actions are present and unedited.

7. Reporting a defect

A useful UAT defect report has six lines. Anything less and it will come back as a question.

1. Surface and URL — for example the dispatch board at /dispatch.
2. Who you were — the account and its role and location scope.
3. The record — the work-order number, asset code or request reference.
4. Steps — numbered, from a known state.
5. Expected versus actual — quote the expectation from the scenario above.
6. Evidence — a screenshot, and the timestamp so the log and audit entry can be found.