tracking_kits/_bmad-output/test-artifacts/test-design-architecture.md

---

stepsCompleted:

• step-01-detect-mode
• step-02-load-context
• step-03-risk-and-testability
• step-04-coverage-plan
• step-05-generate-output lastStep: step-05-generate-output lastSaved: 2026-03-17 workflowType: testarch-test-design inputDocuments:
• D:\Development\Tracking_Kits\docs\project-overview.md
• D:\Development\Tracking_Kits\docs\architecture.md
• D:\Development\Tracking_Kits\docs\module-map.md
• D:\Development\Tracking_Kits\docs\development-guide.md
• D:\Development\Tracking_Kits_bmad-output\project-context.md
• D:\Development\Tracking_Kits\App\Controllers\Kit\KitController.asp
• D:\Development\Tracking_Kits\App\DomainModels\InkjetRecordsRepository.asp
• D:\Development\Tracking_Kits\App\Views\Kit\SwitchBoardPurpleEnvelopeEdit.asp

---

Test Design for Architecture: Purple Envelope Edit and Ballot Range Report

Purpose: Architectural concerns, testability gaps, and NFR requirements for review by Dev/Architecture before adding regression tests for the current purple-envelope workflow.

Date: 2026-03-17 Author: Daniel Covington Status: Architecture Review Pending Project: workspace PRD Reference: Brownfield functional references: docs/project-overview.md, docs/module-map.md, and the currently deployed purple-envelope behavior ADR Reference: Brownfield architecture references: docs/architecture.md and App/Controllers/Kit/KitController.asp

---

Executive Summary

Scope: Preserve current behavior for SwitchBoardPurpleEnvelopeEdit, including report rendering, mixed-format precinct ordering, election-date formatting, color-assignment forms, and print-only report scoping.

Business Context:

• Revenue/Impact: Operational election-mail output; wrong report data can cause incorrect ballot packaging and operator rework.
• Problem: The feature is currently exercised mostly through manual IIS verification, so small controller/view/repository regressions can silently change report output.
• GA Launch: Immediate brownfield regression protection for current production behavior.

Architecture:

• Key Decision 1: Purple-envelope behavior remains in Classic ASP controller/view/repository layers, not a separate service.
• Key Decision 2: Report content is rendered as HTML from KitController + InkjetRecordsRepository + SwitchBoardPurpleEnvelopeEdit.asp.
• Key Decision 3: Mixed-format precinct ordering is handled in VBScript controller helpers, while ballot range aggregation is still SQL-backed.

Expected Scale:

• Single-kit page render with precinct rows sourced from InkjetRecords
• Operator-facing print workflow from browser print preview
• Existing automated test harness limited to ASPUnit helper-style tests

Risk Summary:

• Total risks: 7
• High-priority (>=6): 3 risks requiring mitigation before relying on automated regression coverage
• Test effort: ~14-19 targeted automated checks plus 2 manual print checks (~1-1.5 QA weeks)

---

Quick Guide

BLOCKERS - Team Must Decide

1. R-006: No isolated fixture path for Kit/Inkjet/Settings data - Tests need a disposable MDB or deterministic seed/reset strategy before meaningful controller/repository regression coverage can be added. Recommended owner: Dev.
2. R-002: Ballot range correctness is data-sensitive - We need agreed fixture data covering numeric, zero-padded, and alpha-suffixed precincts plus min/max ballot scenarios. Recommended owner: Dev + QA.
3. R-001: Mixed-format precinct ordering is custom logic - The current order rules must be frozen as explicit expected outputs before tests are written. Recommended owner: Product/Dev/QA.

HIGH PRIORITY - Team Should Validate

1. R-003: Election date formatting/fallback behavior - Approve the rule set: valid dates render Mon-YYYY, invalid or missing values fall back without crashing.
2. R-004: Print-only report scope depends on browser print behavior - Approve a split strategy: automated HTML/CSS assertions plus manual browser print smoke for final confidence.
3. R-005: Color-assignment regressions can hide behind the same screen - Validate that the report tests must also preserve existing AssignKitColorPost and AssignPrecinctColorsPost behavior.

INFO ONLY - Solutions Provided

1. Test strategy: favor repository/controller integration checks plus limited manual IIS print verification.
2. Tooling: reuse ASPUnit, a disposable test MDB copy, and HTML response assertions.
3. Coverage: focus first on sorting, aggregation, date formatting, same-screen regression, and print scoping.
4. Gate guidance: P0 automated checks must pass 100%; P1 >=95%; manual IIS print smoke required before release for print-impacting changes.

---

For Architects and Devs - Open Topics

Risk Assessment

Total risks identified: 7 (3 high-priority score >=6, 4 medium, 0 low)

High-Priority Risks (Score >=6) - Immediate Attention

Risk ID	Category	Description	Probability	Impact	Score	Mitigation	Owner	Timeline
R-001	DATA	Mixed-format precinct sort order changes (0003, 12A, alpha-only values) and produces wrong operator-facing sequence	2	3	6	Lock expected order with seeded regression fixtures and HTML assertions	Dev + QA	Before next release
R-002	DATA	Ballot range query/regression returns wrong low or high ballot numbers per precinct	2	3	6	Add repository-level aggregation checks against known datasets	Dev + QA	Before next release
R-006	TECH	No isolated test-data harness for Kit, InkjetRecords, Settings, and Colors blocks stable regression coverage	3	2	6	Create disposable MDB copy and reset/seeding conventions for tests	Dev	Before automated suite work

Medium-Priority Risks (Score 3-5)

Risk ID	Category	Description	Probability	Impact	Score	Mitigation	Owner
R-003	BUS	Election date header shows wrong format or blank value unexpectedly	2	2	4	Add valid, invalid, and missing-setting render checks	QA
R-004	OPS	Print-only output regresses and shows extra page content or loses repeated-page spacing	2	2	4	Add HTML/CSS assertions and manual print smoke	QA
R-005	BUS	Same-screen changes break existing color-assignment workflows while report tests are added	2	2	4	Add regression checks for both POST actions	Dev + QA
R-007	BUS	Empty precinct data renders broken or confusing output instead of the current no-data row	2	2	4	Add explicit empty-state render test	QA

Risk Category Legend

• TECH: architectural or testability risk
• DATA: incorrect ballot or precinct data interpretation
• BUS: operator-facing workflow correctness
• OPS: environment or print/runtime behavior

---

Testability Concerns and Architectural Gaps

1. Blockers to Fast Feedback

Concern	Impact	What Architecture Must Provide	Owner	Timeline
No disposable test database pattern	Automated tests will share mutable data and become brittle	A documented temp MDB copy/reset approach for ASPUnit-backed integration tests	Dev	Pre-implementation
No render-test seam for controller output	Report assertions stay manual and expensive	A small harness or convention for invoking SwitchBoardPurpleEnvelopeEdit against seeded data and asserting HTML	Dev	Pre-implementation
Implicit behavior contract only lives in code/user feedback	Tests may encode the wrong business rule	A short frozen rules list for sorting, header formatting, and empty-state expectations	Dev + QA + Stakeholders	Pre-implementation

2. Architectural Improvements Needed

1. Stabilize feature fixtures

   • Current problem: no reusable seed set for mixed precinct and ballot-range cases.
   • Required change: create named fixture datasets for numeric-only, zero-padded, alpha-suffixed, alpha-only, and empty-state kits.
   • Impact if not fixed: tests will either miss key edge cases or rely on hand-built ad hoc data.
   • Owner: Dev
   • Timeline: before automated test implementation

2. Separate deterministic logic from page orchestration where practical

   • Current problem: ordering/date helpers are private controller methods, making low-level regression checks harder.
   • Required change: either expose deterministic helper seams or cover the helpers through stable page-render assertions.
   • Impact if not fixed: coverage will skew toward broad render tests only.
   • Owner: Dev
   • Timeline: implementation phase if needed

3. Document browser-dependent print boundaries

   • Current problem: browser headers/footers and repeated-page spacing are only partially controllable in app code.
   • Required change: record which print expectations are automatable versus manual.
   • Impact if not fixed: release disputes on “test passed but print preview changed”.
   • Owner: QA
   • Timeline: before sign-off

---

Testability Assessment Summary

What Works Well

• Existing repository boundaries make ballot-range aggregation testable without full browser automation.
• The report HTML is deterministic from seeded data, which is good for response-body assertions.
• The feature is localized to KitController, InkjetRecordsRepository, KitViewModels, and one view template.
• ASPUnit already exists, so the project has a place to add targeted regression checks.

Accepted Trade-offs

• Browser-generated print headers/footers will remain manual-verification territory.
• Full visual print fidelity on Windows/IIS is accepted as a release smoke check, not a unit-level assertion target.

---

Risk Mitigation Plans (High-Priority Risks >=6)

R-001: Mixed-format precinct sort regression (Score: 6) - HIGH

Mitigation Strategy:

1. Define the expected canonical sort order for representative precinct values.
2. Seed one kit containing 0001, 0003, 12, 12A, 12B, and alpha-only precincts.
3. Assert that both the color table and report table render in the same expected order.

Owner: Dev + QA
Timeline: Before next release
Status: Planned
Verification: Automated HTML assertions against the seeded render output

R-002: Ballot range aggregation regression (Score: 6) - HIGH

Mitigation Strategy:

1. Seed multiple InkjetRecords rows per precinct with known min/max ballot numbers.
2. Assert repository output for each precinct’s low/high values.
3. Assert the rendered HTML shows the same values and no cross-precinct bleed.

Owner: Dev + QA
Timeline: Before next release
Status: Planned
Verification: Repository integration checks plus page-render verification

R-006: Missing isolated test-data harness (Score: 6) - HIGH

Mitigation Strategy:

1. Stand up a disposable test MDB copy for ASPUnit/controller integration runs.
2. Create reset hooks for Kit, InkjetRecords, Settings, and Colors.
3. Document fixture naming and cleanup rules for parallel-safe future tests.

Owner: Dev
Timeline: Before automated suite expansion
Status: Planned
Verification: Test runs can seed, execute, and reset without polluting shared data

---

Assumptions and Dependencies

Assumptions

1. Brownfield docs plus current user-approved behavior are sufficient substitutes for a formal PRD for this feature slice.
2. IIS-backed manual verification remains available for final print checks.
3. Existing status strings and form routing remain part of the contract and should not be normalized during test work.

Dependencies

1. Disposable test data store available before controller/repository automation begins.
2. Mixed-format precinct fixture definitions agreed before expected-order assertions are written.
3. QA has access to a Windows/IIS browser for manual print smoke validation.

Risks to Plan

• Risk: undocumented operator expectations about sort order
  • Impact: the suite may freeze the wrong behavior
  • Contingency: validate the expected fixture output with stakeholders before coding assertions

---

End of Architecture Document

Next Steps for Architecture/Dev Team:

1. Approve the sort-order and date-format behavior contract.
2. Provide a disposable MDB fixture/reset approach.
3. Confirm manual print checks remain part of release validation for this feature.

Next Steps for QA Team:

1. Use the companion QA doc for concrete scenario planning.
2. Build seeded datasets around mixed-format precincts and ballot ranges.
3. Add manual print preview checks only for browser-dependent behavior.