E2E TEST SCENARIOS
VietGara — Owner Web + Admin Web + Backend, Release 1.0–1.4
Version 1.4 — October 17, 2026
1. Purpose
These scenarios test VietGara end to end: through the real owner web, against a running backend, database, Redis, Kafka and mail server. QA engineers run them by hand. Each one is written so that it can later become one automated test (Playwright), with the same ID.
| File | Module | Scenario IDs |
|---|---|---|
| 00_Test_Data.md | Test users, garages, records and the baseline setup | — |
| 01_Identity_Access.md | Sign-up, e-mail verification, sign-in, Google, password reset, user, language, platform admins | E2E-IAM-* |
| 02_Garage_Staff.md | Garages and settings, staff invitations, members, roles and groups, tenant isolation | E2E-TEN-* |
| 03_License_Subscription.md | Trial, plan changes, plan limits, read-only and suspended modes, platform-admin plans and subscriptions | E2E-LIC-* |
| 04_Customer_Vehicle_Partner.md | Customers, consent, vehicles, partners, permissions | E2E-CUS-* |
| 05_Quote_Pricing.md | Quotes, line items, LINK/MANUAL approval, the public approval link, conversion to a repair order | E2E-QUO-* |
| 06_Repair_Order.md | The Kanban board, technician assignment, line progress, closing | E2E-REP-* |
| 07_Inventory.md | Goods receipts with a supplier per line, cost and valuation, part suppliers, stock on hand, stock issues and reservations, stock counts, write-offs and returns, barcodes and the Excel import, the stock movement report, automatic deduction on close, cost visibility | E2E-INV-* |
| 08_Settlement.md | Settlements, payments, payment vouchers, voids, the receipt PDF, the dashboard figure | E2E-BIL-* |
| 09_Catalogue.md | Parts, units and packaging, categories and brands, selling prices, images, Excel exports, catalogue permissions (Release 6.0) | E2E-CAT-* |
2. Scenario format
Every scenario has the same parts:
### E2E-TEN-007 · Invite an existing user by e-mail and accept from the e-mail link
**Priority:** P1 · **Covers:** FR-TEN-04, FR-NOT-04 · **Automation:** Candidate
**Preconditions:** baseline (00_Test_Data §4). Signed in as `[email protected]`, active garage **QA Gara 1-1 Quan 1**.
**Steps**1. …
**Expected results**- …| Field | Meaning |
|---|---|
| ID | E2E-<MODULE>-<NNN>. Never renumber or reuse an ID: automated tests and bug reports refer to it. New scenarios take the next free number |
| Priority | P1 smoke: run on every build given to QA and before every release. P2 regression: run before every release. P3 edge case: run when the area changes |
| Covers | The FRD requirements (and NFRs) the scenario checks |
| Automation | Candidate: can be automated as written. Manual only: needs a real third party (Google) or human judgement. Automated: an automated test with this ID exists (update this field when it lands). Automated (API, partial): a blackbox test with this ID covers the API-level steps; the browser-only steps are still manual or planned for vietgara-e2e (testing/blackbox/scripts/check_traceability.py in vietgara-backend lists them) |
| Preconditions | The state before step 1. “Baseline” means the data built by the baseline setup in 00_Test_Data.md §4 |
| Test data | The named users and records from 00_Test_Data.md that the scenario uses |
| Steps | What the tester does, described as user actions (“invite … by e-mail”), not screen coordinates |
| Expected results | What must be true afterwards. Messages are quoted in English; the Vietnamese text must show the same meaning when the interface is in Vietnamese |
Rules for writing new scenarios:
- Use the named test data. Never “some user” or “a garage”: always
[email protected]or QA Gara 1-2 Thu Duc. Add a new named record to 00_Test_Data.md when none fits. - One behaviour per scenario. A scenario that fails should point to one defect.
- Do not depend on another scenario. Start from the baseline, or list the extra setup under Preconditions.
- Scenarios that create single-use users (sign-up tests) use
signup.<scenario id>.<unique>@vietgara.test, for example[email protected], so the e-mail says which scenario created it.
3. Test environment
3.1. Local (Docker Compose)
Start the stack as described in the backend README (vietgara-backend/README.md), with these values in vietgara-backend/.env:
| Variable | QA value | Why |
|---|---|---|
PLATFORM_ADMIN_EMAILS | [email protected] | Makes the QA admin user a platform admin |
LICENSE_EXPIRY_JOB_INTERVAL | 1m | Trial expiry and read-only scenarios take one minute instead of one hour |
ENTITLEMENT_CACHE_TTL | 1m | Subscription changes made through SQL show within one minute |
JWT_ACCESS_TTL | 20m (default) | Keep the default; E2E-IAM-010 relies on it |
MAIL_PROVIDER | smtp (Mailpit) | Every e-mail is caught by Mailpit and never leaves the machine |
| Address | What |
|---|---|
| http://localhost:8000 | Owner web (through Kong) |
| http://admin.localhost:8000 | Admin Web (through Kong; the browser resolves *.localhost to loopback) |
| http://localhost:8025 | Mailpit: every e-mail sent (OTP codes, invitations, reminders) |
All test e-mails use the domain vietgara.test. The .test domain is reserved (RFC 2606) and can never belong to a real person, so no real mailbox ever receives test mail.
3.2. Staging
Staging sends real e-mails through Mailjet, which cannot deliver to vietgara.test. On staging, replace the domain with plus-addresses of a mailbox the QA team owns, keeping the local part:
[email protected] → <qa-mailbox>+owner1@<qa-domain>
Only E2E-IAM-014 to E2E-IAM-016 (Google sign-in) need a real Google account; see 00_Test_Data.md §2.
3.3. Reading e-mails
Open Mailpit (http://localhost:8025) and search by the recipient address, for example to:[email protected]. The newest message is on top. Check:
- the subject and body language match the user language (Vietnamese by default);
- the OTP is 6 digits and the e-mail says it is valid for 2 minutes;
- links (invitations) start with the owner web address.
3.4. Moving time forward (SQL helpers)
Some rules depend on time (trial end, grace period, invitation expiry). Rather than waiting days, QA moves the stored dates with SQL. Connect as the schema owner:
docker exec -it vietgara-pgsql psql -U user -d testdb| Helper | SQL | Then |
|---|---|---|
| H1 End the current period (trial or paid) | UPDATE subscriptions SET current_period_end = now() - interval '1 minute' WHERE user_id = (SELECT id FROM users WHERE email = '<owner e-mail>'); | Wait up to 1 minute: the expiry job moves it to Past due (read-only) with a 7-day grace period |
| H2 End the grace period | UPDATE subscriptions SET grace_period_end = now() - interval '1 minute' WHERE user_id = (SELECT id FROM users WHERE email = '<owner e-mail>'); | Wait up to 1 minute: the subscription becomes Suspended |
| H3 Bring the period end within 7 days | UPDATE subscriptions SET current_period_end = now() + interval '3 days', reminder_period_end = NULL WHERE user_id = (SELECT id FROM users WHERE email = '<owner e-mail>'); | Wait up to 1 minute: the “expiring soon” reminder e-mail is sent |
| H4 Expire a pending invitation | UPDATE staff_invitations SET expires_at = now() - interval '1 minute' WHERE status = 'pending' AND user_id = (SELECT id FROM users WHERE email = '<invitee e-mail>'); | Takes effect at once |
| H5 Check subscription state | SELECT a.email, p.code, s.status, s.trial_end_at, s.current_period_end, s.grace_period_end FROM subscriptions s JOIN users a ON a.id = s.user_id JOIN plans p ON p.id = s.plan_id WHERE a.email = '<owner e-mail>'; | Read only |
SQL helpers are part of a scenario’s setup, never its checks: every expected result is checked in the owner web or in Mailpit. When a scenario is automated, the helpers become API or database fixtures.
3.5. Resetting the environment
Sign-up e-mails can be used only once. To run the whole suite again, either:
- reset the database: stop the stack, delete the Postgres data directory mounted in
vietgara-backend/docker-compose.yml, start the stack and repeat the baseline setup. This deletes all local data, not only test data; or - add a run number to single-use e-mails:
signup.iam001.r2.<unique>@vietgara.test. Baseline users stay as they are.
4. Recording results
Record each run in the release’s test-run sheet with: scenario ID, build (owner web and backend versions), environment, tester, date, result (Pass, Fail, Blocked, Not run) and the bug ID for every failure. A bug report quotes the scenario ID and the step number that failed.
5. Path to automation
- Scenarios marked Candidate are automated first, P1 before P2.
- The automated suite reuses the test data names in 00_Test_Data.md. The baseline setup becomes an API-driven fixture instead of clicks.
- Each automated test is named after its scenario, e.g.
test('E2E-TEN-007 invite by e-mail and accept', …). - When a test lands, set the scenario’s Automation field to Automated. The manual run keeps only what is still manual.
4. Planned scenario files
Each release adds scenarios in the file of its module, or a new file when there is none. Write them with the release, using the next free ID. From Phase 4 the Definition of Done of every release includes its blackbox scenarios and, where the UI changes, its web E2E scenarios. The shared test data is the YAML dataset of vietgara-testdata (Release 4.0); 00_Test_Data.md is generated from it.
| Release | File | Scenarios to add |
|---|---|---|
| 3.0-3.1 | all | Names change from account to user; no new scenarios |
| 4.1-4.2 | 01-08 | Blackbox and web automation of the P1 and most P2 scenarios of the stable modules |
| 5.0 | 04, 08 | Delete versus deactivate and reactivate; legal header on PDFs; voucher number, print and void |
| 5.0 | 04, 01 | Partners screen renamed Suppliers: no insurer type, supplier.* permissions; edited name survives a Google sign-in; schema test for audit columns (not a UI scenario) |
| 5.1 | 04, 05 | Walk-in customer without a user; search by phone or e-mail; link request accepted and declined; company with two tax profiles on a quote; invoice requested refused with an incomplete profile; vehicle plate locked by a live quote, editable after the quote is deleted, corrected by staff with customer.correct |
| 5.2 | 03 | Plan change scheduled for the period end (pending shown, cancelled, re-scheduled); applied by the daily job; downgrade postponed when usage is too high |
| 6.0 | 09 E2E-CAT-* | Selling price per unit and packaging override, quote line prefilled and unchanged by a later price change; units and conversion (receive by the case, issue by the can); category and brand search; part image; revenue and inventory Excel (written: 09_Catalogue.md) |
| 6.1 | 01 | MFA enrolment, sign-in with the code, recovery code used once, lockout after five wrong codes, regenerate and turn off, Google sign-in exempt (written: E2E-IAM-022 to 027 in 01_Identity_Access.md) |
| 7.0 | 07 E2E-INV-* | Goods receipt with a supplier on each line (blocked when missing), completion and average cost, cancel and its refusal, part suppliers, purchases and valuation with Excel, cost hidden from technician; repair order’s draft stock issue reserves parts, “issue now”, posting on close once, posting on start (written: E2E-INV-011 to 019 in 07_Inventory.md) |
| 7.1 | 07 E2E-INV-* | Count with matched, over and short lines, refused while a line is uncounted; packaging unit and zero count; merge of drafts and skipped lines; cancel of a draft and reversal refused once the stock is used; count Excel with cost by role; write-off at average cost; return to supplier with its credit; return of unused repair order parts; stock card entries; permissions (written: E2E-INV-020 to 029 in 07_Inventory.md) |
| 7.2 | 07 E2E-INV-* | Several barcodes per part for the base unit or a case, unique per garage, lookup and search; scan into a receipt and a count (web and phone); Excel import of parts with all problems listed and nothing saved, then the fixed file with units, barcodes and opening stock; the same file refused twice; goods receipt and stock count files as drafts; permissions by type and by column; unreadable, oversize and incomplete files (written: E2E-INV-030 to 038 in 07_Inventory.md) |
| 7.3 | 09 E2E-CAT-*, 05 E2E-QUO-*, 06 E2E-REP-* | A job with suggested parts (name, price, duration, hidden consumables) created and validated; delete or deactivate and reactivate; the parts and packaging units a job uses are protected; job permissions; a job picked on a quote (labor and part lines, editable, packaging units); hidden consumables not billed, shown or decided and following their job at conversion; lines of an open order added, edited and removed with the draft stock issue following; a posted issue freezes the parts; cancel before work starts and the reservation released; waiting on parts served first come, first served and cleared by stock; line and cancel permissions (written: E2E-CAT-010 to 013, E2E-QUO-015 to 017 and E2E-REP-013 to 018 in 09_Catalogue.md, 05_Quote_Pricing.md and 06_Repair_Order.md) |
| 7.2-7.3 | 07, 05, 06 | Barcode, Excel import; job picker, hidden consumables and stock reservation with waiting on parts (7.3) |
| 8.0-8.2 | 01, 10 E2E-PLT-* | Rate limit answers; platform roles and groups; admin staff permissions; support grant request, owner approval, read-only session, revoke, audit |
| 9.0 | none | The load test is a script in vietgara-e2e, not a scenario here |
| 10.0-10.1 | 05, 11 | A4 and A5 print; e-mail at each hand-off; low-stock alert |
| 11.0-11.4 | 12 E2E-BKG-* | Settings and slots, capacity race, booking from the app (push) and from the public page (OTP, hold expiry), reminders, reschedule, convert, bays; admin dashboard figures |
| 12.0-13.2 | 08, 13 | Receivables reminders, phiếu chi, purchase orders, payables, reports, data requests, thermal and LAN printing, print agent, template designer |
| 14.x | 07, 14 | Transfers between garages; multi-garage dashboard |
| 16.x, 17.x | 15, 16 | Payment, e-invoice, SMS/Zalo; immediate paid upgrade with proration while a downgrade stays pending; insurers directory and claim tracking; supplier link and portal |