meguri/docs/testing.md

# Test architecture

The daily cover workflow has a PostgreSQL regression for read-only preview, volunteering, owner approval, denied self-approval/third-party transfers, force permissions, empty comments and current-interval clipping. `tests/browser-cover.cjs` creates its own workspace and checks calendar → offer → owner acceptance, own-day request → exact-request acceptance, the privileged third action without a comment, early range errors, comment visibility, display timezone and mobile layouts. Browser navigation opens Setup explicitly; daily flows do not need it.

Scheduling errors are product failures. A change to ownership, time boundaries, approvals, access, or synchronization must include a regression at the boundary that could fail. Test observable outcomes rather than repeating an implementation formula.

| Layer | Location | Dependencies | Contract |
|---|---|---|---|
| Pure engine | `src/engine.rs` tests | None | Owners and intervals, DST, fallback, pending/applied overrides, validation |
| Configuration graph | `src/configuration.rs` tests | None | Dependency removal/redirect, last-step and fallback protection, pending swap cancellation, approved-history retention, exact route permutation |
| CSV import | `src/holidays.rs` tests | None | Country/date keys, quoting, BOM, duplicates, conflicts, invalid rows |
| Provider compilation | `src/providers/` tests | None | Unsupported capabilities fail; normalization detects changed ownership |
| Application/persistence | `tests/integration.rs`, `tests/support/` | Disposable PostgreSQL | Real Cot migrations, scoped authorization, concurrent edits, atomic audit/history/outbox, approval revalidation |
| HTTP provider contract | Integration suite + stateful local fake | PostgreSQL + loopback | Wire methods/payloads, partial 429 failure, checkpoint recovery, read-back, drift, external overrides, owned-only deletion |
| Browser/API | `tests/browser.cjs`, `tests/browser-calendars.cjs`, `tests/browser-configuration.cjs` | Seeded local app + Chromium | Forms, calendar, approval, workspace isolation, CSRF/origin, people/imports/timezones, removal dependencies, native routing drag/drop and position editing, desktop/mobile |
| Live acceptance | Dedicated JSM test team | Test credentials | Actual provider timeline, subscription-specific escalations and routing; never ordinary CI |

## Invariants

- Every schedule covers the requested range without gaps or overlaps. Tests exercise a year across five zones and five shift lengths.
- Spring and autumn weekly shifts can be 167 or 169 hours while handing over at 11:00 local. Exact boundaries belong to the incoming employee. Invalid local handovers fail.
- Overrides change only their interval, not the base sequence. Pending requests have no effect. Overlapping approved state is an error.
- Coverage uses secondary, then the effective fallback including overrides. Country holidays skip only affected people; legacy global holidays select fallback directly. Cycles fail validation.
- Swaps apply both legs or neither. Requesters cannot approve for someone else. Application rechecks availability and ownership. Force requires a grant and is audited; comments are optional.
- One of two edits with the same revision wins. A failed constraint leaves document, revision, history, audit, and job unchanged.
- Schedule removal rewrites references, cancels affected pending requests in full, and commits one history/audit/outbox change. It cannot erase a current/future approved replacement or leave an empty escalation or broken fallback.
- Route ordering requires every current ID exactly once. Missing, repeated, foreign, stale, or unauthorized requests change nothing. Changing priority preserves conditions/recipients and survives reloads.
- Publication snapshots cannot read newer revisions. Past absence flags do not block a now-correct future plan.
- Competing workers cannot claim the same unexpired lease. Retrying a lost checkpoint does not create duplicate remote resources.
- External changes and overrides block writes/deletion by default; unmanaged resources survive reconciliation.

## Running and extending

`cargo test` runs pure tests and explicitly reports database tests as ignored. CI also runs `cargo test --test integration -- --ignored --test-threads=1` with PostgreSQL 17. Fixtures use UUID names and never truncate shared tables. Use a disposable database. Run this suite serially because worker tests inspect the global queue. Worker tests explicitly prioritize only their own job so a bounded batch cannot skip it because of jobs left by a prior run.

The fake models JSM responses and is not a substitute for live acceptance. New endpoints need verification against official documentation, a wire assertion, and a failure/recovery test. Do not make the fake accept an invented contract to get tests green.

Before enabling a provider in production: publish a preview to its dedicated test team, compare the actual timeline, repeat unchanged, interrupt a partial publication, introduce external drift, verify conflict and explicit overwrite, and exercise escalation/routing on the target subscription. Record evidence and limitations.
## Additional regression cases

Cover independent handovers and dependent fallback boundaries, DST rejection, country-specific coverage, scoped directory selection, email contacts without access, import quoting/BOM/duplicates/errors/stale previews, atomic working-interval propagation, and exact JSM email resolution before writes. Browser coverage includes person selection by email, absence selection, reactive CSV preview/import, and readable escalation/routing flows on desktop and mobile.

## Variables, absence planning, and demo lifecycle

`src/absence.rs` tests range splitting across independent handovers, automatic project promotion, uncovered diagnostics, preserved owners, and replacement validation. `tests/generation.rs` checks deterministic 30-project expansion, stable IDs on rename/reorder, typed dictionary errors, loop scope, fallback cycles, protected applied replacements, workspace-specific IDs, three-person priority, country holidays, and a Monday rotation crossing autumn DST.

The PostgreSQL suite checks read-only previews, grouped absence approvals, atomic workspace-variable activation, permission isolation, stale reviews, concurrent activation, country snapshots, and no contact-to-login grants. Demo tests use uniquely named disposable databases with CREATEDB: unmarked/normal protection, safe isolation, application-only reset with unrelated sentinel data preserved, repeated migration/seed, creation-based soft deletion, later physical purge, and reseeding. Never repoint these tests at a production DB.

The two additional browser suites (`browser-absence.cjs`, `browser-generation.cjs`) exercise actual forms and early server errors, persistent/reloaded state, the permanent demo banner and login guide, generated source editing, country accordions, DD-MM-YYYY, bulk replacements, and desktop/mobile layouts. Inspect screenshots rather than trusting DOM assertions alone.

Localization/navigation regressions check supported browser fallback, persistent account preference, parameter safety, complete catalogs, no literal template text, direct links, reload, workspace changes and browser history. Generation browser checks retain server errors, atomic activation and stable generated IDs while exercising inline controls and the source-owner link.

Exact-time cover regressions exercise same-day partial cover, workspace clock defaults despite a different display zone, server ownership checks, malformed clock values, DST folds/gaps and 23/25-hour calendar days. Generator browser tests assert that binding edits replace the main form and live validation remains inside the viewport even at the top of a long form.


Legacy compatibility regressions deserialize two-person schedules and dynamic generation bindings into priority-owner resources while preserving participant order, resource identity, fallback, handover and routing references.

`tests/browser-binding-preview.cjs` checks reactive formatted binding values beside server type errors, clearing missing selections, first-row lookup context and mobile sizing without saving draft changes.

`browser-generation-scroll.cjs` checks scroll restoration from an editor near the bottom of a long rule on desktop/mobile and verifies template styling is limited to non-interactive blocks.
`audit` unit tests preserve comments and unknown IDs while resolving references. PostgreSQL regression checks historical names after rename, raw UUID preservation and cross-workspace lookup isolation.

`browser-setup-layout.cjs` checks compact review state, country holiday counts, collapsed widgets, import access and mobile width. Demo holiday imports also run through integration seed/reset checks.


Repeated-cover regressions check approval gating, partial interval splitting, preserved original legs, stale-owner rejection, forced corrections and calendar interaction on an already replaced day.

The setup inventory browser checks cover collapsed resource rows, the schedule-type creation chooser, top utility widgets, desktop/mobile sizing, and absence of the old anchor/example controls. Configuration browser checks expand manual rows before deletion/reordering and retain drag-and-drop routing coverage.

Advanced demo regression checks dependent iteration filtering, inherited regional handovers/participants, tier-based escalation settings and working windows, shared tier edits with stable resource IDs, and early validation of a newly enabled entry with a missing tier. Integration seed/reset verifies all four workspaces.

`browser-advanced-demos.cjs` opens both advanced generation editors, verifies clean server previews, and checks the demo workspace access matrix for Alice, Bob and Carol.

Setup layout checks also verify iteration-source summaries, omission of zero iterations, collapsed resource descriptions and source-rule navigation for all three resource kinds.

Diagnostics regression covers bad participant data, primary/secondary errors, scoped source links, draft-preserving navigation, always-visible status and recovery to valid. Absence tests cover exact interval selection, independent schedule ranges, rejection of overlap/out-of-absence bounds, and unchanged bulk range behavior.

`browser-diagnostics.cjs` exercises invalid participant data, rule/variable links with local draft retention, and recovery to a valid status on mobile. `browser-absence.cjs` additionally selects an uncovered impact row and checks exact schedule/time bounds before the existing bulk workflow. PostgreSQL tests verify exact absence coverage remains pending until approval and leaves surrounding hours uncovered.

Unified absence editor tests change the start time of a shortcut-created range, verify resulting server boundaries, and use the same date/time controls for manual ranges. Unit coverage includes local range scope, half-open bounds and DST rejection.

Coverage diagnostics distinguish pending approval from missing substitutes. Pending request boundaries split uncovered intervals so partial requests never disguise remaining gaps. The UI shows substitutes and outstanding approvers, links to requests, and keeps publication blocked until approval. Browser regression covers partial pending coverage, remaining gaps, approver filtering, and responsive spacing.

Schedule setup places narrower variable and generation-rule panels beside a stacked availability sidebar. Absences and holidays remain open; their lists scroll internally. Country holiday groups retain accordions inside the bounded list, with add/import actions opening dialogs. Responsive layout moves the sidebar below the editors. Browser checks cover column position, bounded holiday expansion, visible actions and mobile width.

Generated routing placement is shown only when manual routes and an enabled route-generating rule coexist. Options name the manual routes in evaluation order; the stored insertion index is unchanged. Browser checks verify hidden controls for generated-only setups and named options/order for mixed routing.

Resource inventory is a distinct UI component (`resource-inventory.html`). All expanded resource kinds share `resource-details.html`: labeled icon rows, consistent spacing, sequential connectors, and a common source-rule control. Presentation rows and monochrome SVG paths come from pure UI helpers; schedules, routing order and provider state are unchanged. Check rotation, fixed owner, priority fallback, escalation timing/repeats and routing conditions on desktop/mobile.

Expanded resources use compact type-specific horizontal widgets instead of parameter tables: rotation metadata plus ordered people, priority people plus fallback, escalation steps plus repeat footer, routing conditions plus destination. Shared icon, chip and connector styles keep them consistent. Chains wrap within narrow screens; source links and edit actions retain their common placement.

The generation-rule editor is a generic technical constructor: visible iteration aliases and collection bindings, an explicit optional condition, and typed output blocks. New rules start without implicit project/responsible-variable detection or generated blocks. Variable names carry no semantic meaning. Compact controls retain the existing typed binding editor, value preview, live server diagnostics and draft semantics. Check no-iteration rules, nested collection bindings, conditions and multiple output types on desktop/mobile.

Binding selection uses one anchored, viewport-clamped popover beside the originating control; the constructor remains visible and keeps its scroll position. All source kinds, nested lookups/lists, paths, text affixes and live value previews remain supported. Literal escalation delays are directly editable. Done/Escape closes the popover and returns focus. Server and change previews are collapsed summaries with counts and bounded change lists. Browser checks cover context retention, source editing, nested bindings, keyboard dismissal and mobile bounds.

`browser-repeat-defaults.cjs` verifies absent escalation defaults render as editable numbers, edited values survive reopening the draft, and explicit dictionary lookups remain intact.

The main Acme Engineering demo contains six services (Payments, Search, Billing, Identity, Data platform, Developer portal), each with two or three ordered owners drawn from five login members: alice, bob, carol, dave, erin. All five share the weekly Monday 11:00 Time off rotation. Dave and Erin only access Acme; Carol also retains Support/Commerce access. Other demo workspaces remain separate. Login password remains `meguri-demo-only`.

Generation rule results use the actual authorized server expansion, including schedules, escalation policies and routes, with resolved names and compact settings. The panel is always present with explicit checking, invalid, disabled and empty states; it respects iteration filters and does not simulate generation in the browser. Preview data contains only scheduling resources and scoped people, never integration configuration.

Permanent assignees are tested as single-participant rotations, including absence, replacement approval and publication blocking. The removed fixed-assignee schedule and generation types are rejected rather than normalized.

Workspace isolation regressions exercise independent memberships and variables, a single revision for configuration and working-time changes, read-only generation preview, stale review rejection, atomic activation/history/outbox, and owner settings permissions.

The default Engineering example stores projects as one list of dictionaries: each entry has `name` and an ordered `responsible` person list. The Project iteration reads both fields directly from its current entry; no parallel responsible lookup variable is needed. The independent `on_call` list still defines the shared weekly rotation.

Variable editing uses a bounded, progressively disclosed tree: only the root starts expanded, object rows show names and collection summaries, and nested values expand in place. Values mode hides type/key controls; Structure mode exposes them without losing edits. Duplicate assigns fresh IDs recursively; ordering and live server validation remain intact. Check nested editing, duplication, mode switching and narrow viewports.

Generation map opens from Generation rules as a read-only, draggable/zoomable Cytoscape canvas. Server preview returns actual iteration counts, input contexts, predicate outcomes and produced IDs; no scheduling evaluation is duplicated in JavaScript. Iterated outputs start collapsed into a group; inspecting a node or pass reveals source data and verified resources. Invalid drafts show diagnostics rather than stale resources. The map is a captured draft preview refreshed explicitly, and never applies changes. Bundled Cytoscape 3.33.1 is served locally with its MIT license; no CDN or new framework is required. Browser coverage checks groups, details, source navigation, pan/zoom and mobile layout; engine regression verifies traced pass results.

The generation map arranges numbered rules in saved execution order from left to right, joined by solid sequence arrows. Each rule owns a vertical column of iterations, conditions and outputs. Dashed secondary edges show data dependencies rather than execution order. Repeated output groups use offset background cards; decorative layers follow dragging and do not receive selection. Browser checks verify rule ordering, aligned output columns and stack movement.

Map input details display evaluated server values for each block and pass, never serialized bindings. Shared values are deduplicated across passes; differing values are explicitly counted. Generated references collapse to type/name cards, and people resolve by display name. Empty binding metadata and raw reference UUIDs are not presented. Condition operands and escalation recipients/delays come from the same resolver used during expansion.

The map’s all-passes input overview lists deduplicated upstream sources, not expanded output settings: variables with used binding addresses and resource references grouped by producing block. References internal to the selected whole rule are omitted; selecting an individual output block shows its dependencies. Selecting a concrete pass still exposes its evaluated field values.

Expanded map resources use type-specific labeled fields and the same compact reference cards as inputs, never JSON dumps. Priority schedules show ordered people, fallback and zoned handover; rotations add anchor/cycle; policies show recipient/timing/condition and repeat behavior; routes show conditions, working window and destination. Reference names resolve from the preview snapshot. Browser regression checks visible names, participant order and absence of UUID metadata.