Skip to content
VietGara Docs

RELEASE PLAN — PHASE 4

VietGara — Quality Foundation

Version 4.1 — October 12, 2026 · Cloud: Google Cloud Platform (GCP) · Backend: Go

1. Introduction

Unit tests are strong (most packages at 90% or more). The gap is everything between modules: the API contract, cross-tenant isolation, plan limits, the mobile BFFs, the PDFs, e-mails and the web UI.

This phase goes before the large changes of Phases 5–8 (flexible customers, units, vouchers, inventory documents, platform staff). Those changes get their own scenarios inside their releases; this phase only covers modules that are stable now.

Rule for every later release. The Definition of Done of each release includes its blackbox scenarios and, where the UI changes, its web E2E scenarios. Test debt is not carried forward.

Scope boundaries:

  • In scope: backend (blackbox) and the two web consoles (Playwright).
  • Out of scope for now: Flutter device tests. The apps keep their own unit and widget tests and rely on the API suite for the contract. Device smoke tests are planned later, once the apps have changed in Phases 5–12.

2. Overview of the 3 Releases

ReleaseNameMain ModulesDemoable Value
4.0Test Data & Toolingvietgara-testdata (new repo), seeder, purge, CIOne command seeds the same named dataset on the stubbed stack or on staging, and removes it afterwards
4.1Blackbox API Coveragetesting/blackboxAll P1 and most P2 scenarios of the stable modules pass at API level; coverage of API operations is measured
4.2Web E2Evietgara-e2eThe P1 scenarios run in a browser on every pull request and the full set nightly

3. Release Details

Release 4.0 — Test Data & Tooling

  • New repository vietgara-testdata (private), consumed by both the backend blackbox module and vietgara-e2e:
    • a JSON Schema and the YAML dataset: users, garages, staff, groups, roles, customers, vehicles, suppliers, parts, plans;
    • a small loader in Go and one in TypeScript (an npm package), versioned by tags; each suite pins a tag;
    • the seed and purge definitions.
  • Naming is short and predictable: owners owner1, owner2; garages gara1-1 and gara1-2 (first and second garage of owner1), gara2-1; staff advisor1-1, technician1-1, inventory1-1 (role, owner, garage); customers customer1-1-1; platform users admin and support1. E-mails use the test-routed domain, never a real domain, so mail lands in Mailpit.
  • Two kinds of data. Baseline data has fixed names and is read-mostly; tests must not leave it changed. Scenario-owned data is created by the test with a unique suffix (sign-up, password reset, destructive scenarios) and deleted in teardown.
  • Passwords. One shared password for all baseline users on the local and stubbed stacks, kept in the dataset. On staging the dataset holds only a reference (passwordRef); the value is a CI secret, the same for every persona, and the platform admin has a separate, stronger secret. When MFA ships, test admins get a fixed TOTP secret from the dataset or a secret so tests can compute the codes.
  • Seeder. A command that creates the dataset through the public API (and Mailpit for verification codes), idempotently, against any target. The platform admin is bootstrapped from configuration, not by sign-up.
  • Purge. The API cannot remove used records (the delete-or-deactivate rule keeps them), so the purge is a privileged, test-only operation: a cascade hard delete of every user under the test domain with their garages, files, outbox rows and Mailpit messages. It is off in production by configuration, refuses anything outside the test domain, and requires a marker on the records. The stubbed stack is simply torn down with its volumes. On staging the flow is seed → run → purge, and a sweeper removes leftovers of crashed runs after a few hours.
  • Traceability. 00_Test_Data.md is generated from the dataset. A check fails the build when a documented scenario ID has no test or a test names an unknown ID, and an OpenAPI report lists the operations no blackbox test calls.
  • Access to the private repository. vietgara-testdata stays private. Each consumer (the backend, vietgara-e2e, and the docs repository for the generated test-data document) reads it through a read-only deploy key on vietgara-testdata, stored as a repository secret TESTDATA_DEPLOY_KEY in each consumer (organization-level secrets need a paid GitHub plan, so the key is set per repository). CI checks out the pinned tag with actions/checkout (repository, ref, ssh-key) into .testdata/; a testdata.version file in each suite names the tag, and a bump is a normal pull request (Dependabot cannot see a private repository). The Go and TypeScript loaders are used from the checked-out copy (a Go replace or go.work, a file: dependency) instead of private package registries, so no GOPRIVATE or package token is needed for them. Developers run make testdata, which clones the pinned tag with their own GitHub access into .testdata/. Forks get no secrets.
  • CI. Both suites run against the stubbed stack on every pull request (smoke) and nightly in full; JUnit reports and Playwright traces are kept on failure.
  • Definition of Done: make seed and make purge work on the stubbed stack and on staging; both suites read the same dataset; the generated test-data document matches the dataset; the traceability and coverage reports run in CI.

Release 4.1 — Blackbox API Coverage

  • Write the P1 and most P2 scenarios of docs/05-Testing/E2E_Scenarios at API level for the stable modules: Identity (sign-up, verification, sign-in, password reset, Google through the stub), Tenant (garages, invitations, roles, groups, cross-tenant isolation), License (plans, limits, read-only and suspended modes), Customers, Vehicles and Suppliers (partners until Release 5.0), Quotes (link and manual approval, daily limit), Repair Orders, Inventory, Settlements, Reporting, PDFs and Excel (valid file and correct numbers), the Technician and Customer BFFs, and the e-mails read from Mailpit.
  • Add 08_Settlement scenarios (Settlement & payments) as written in the E2E documents.
  • Raise the unit coverage of the money path to the 90% gate: billing handler (63%) and domain (68%), repair order domain and handler (about 70–75%).
  • Scenarios about flows that Phases 5–8 change (customer picker, units, vouchers beyond the basics, insurer split) are not written here.
  • Definition of Done: every P1 scenario of the stable modules passes; at least 80% of API operations are called by a blackbox test; the 90% gate holds on the money path.

Release 4.2 — Web E2E

  • Playwright suites for vietgara-owner-web and vietgara-admin-web with page objects, role-based locators and the shared dataset.
  • All P1 scenarios and selected P2 scenarios of the stable modules; a @smoke tag runs on every pull request, the full set nightly against the stubbed stack and weekly against staging.
  • Traces, screenshots and video on failure; a flaky-test rule: a test that fails and passes on retry is quarantined and fixed within one sprint.
  • The viewport check script from the UI audit becomes a test at 1440 / 820 / 390 px.
  • Definition of Done: the smoke set runs in under 10 minutes on every pull request; the full set is green nightly for a week; no skipped test lacks a ticket.

4. Dependency Diagram

flowchart TD
  P3(["Phase 3 complete"]) --> R40["Release 4.0<br/>Test data & tooling"]
  R40 --> R41["Release 4.1<br/>Blackbox API coverage"]
  R40 --> R42["Release 4.2<br/>Web E2E"]
  R41 --> DONE(["Phase 4 complete"])
  R42 --> DONE

Releases 4.1 and 4.2 depend only on 4.0 and can run in parallel. Mobile device smoke tests (one per Flutter app on an emulator) are a later item, scheduled after the apps stabilize.