---
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.