STD: Specimen Type Management (SPECIMEN)

Version: v3.1.0 Status: Draft SRS Source: docusaurus/docs/srs/kitcfg-specimens.md Domain: SPECIMEN

---

Overview

This document specifies tests for the Specimen Type Management domain, which covers specimen type CRUD, target name suffix-to-specimen mapping, and automatic specimen derivation during runfile import. All capabilities in this domain are new in v3.1.0.

Domain Characteristics:

• Primary function: Specimen type configuration management (CRUD operations)
• Secondary function: Target name suffix-to-specimen mapping (CRUD and derivation)
• Tertiary function: Automatic specimen assignment during import via suffix matching
• Configuration dependency: use_sample_type client configuration, help_items feature flag, site scoping

Test Method Rationale: Per Test Plan section 3.3, configuration domains use TM-API as primary method with TM-UI fallback. Specimen management endpoints have deterministic validation logic (uniqueness, site scoping, case-insensitive suffix matching). API-level testing provides faster, more reliable coverage. UI testing supplements for access-control visibility (sidebar links, Config Mode gating).

Test Case Convention: Steps describe logical actions, not UI mechanics. Use "Create specimen type" or "Submit suffix mapping", not "Click the Add button" or "Select from dropdown". This ensures test intent survives UI redesigns.

---

Coverage Summary

REQ ID	Title	ACs	Tests	AC Coverage	Method	Gaps
REQ-SPECIMEN-001	Specimen Types Page Access	4	TC-SPECIMEN-001	4/4 (100%)	TM-API, TM-UI	None
REQ-SPECIMEN-002	Specimen Types Table	5	TC-SPECIMEN-002	5/5 (100%)	TM-API	None
REQ-SPECIMEN-003	Add Specimen	6	TC-SPECIMEN-003	6/6 (100%)	TM-API	None
REQ-SPECIMEN-004	Edit Specimen	5	TC-SPECIMEN-004	5/5 (100%)	TM-API, TM-UI	None
REQ-SPECIMEN-005	Delete Specimen with Warning	3	TC-SPECIMEN-005	3/3 (100%)	TM-API	None
REQ-SPECIMEN-006	Target Suffix Page Access	4	TC-SPECIMEN-006	4/4 (100%)	TM-UI	None
REQ-SPECIMEN-007	Target Suffix Mapping Table	5	TC-SPECIMEN-007	5/5 (100%)	TM-API	None
REQ-SPECIMEN-008	Add Target Suffix Mapping	6	TC-SPECIMEN-008	6/6 (100%)	TM-API	None
REQ-SPECIMEN-009	Edit Target Suffix Mapping	6	TC-SPECIMEN-009	6/6 (100%)	TM-API	None
REQ-SPECIMEN-010	Delete Target Suffix Mapping	4	TC-SPECIMEN-010	4/4 (100%)	TM-API	None
REQ-SPECIMEN-011	Suffix Matching During Import	4	TC-SPECIMEN-011	4/4 (100%)	TM-API	None
REQ-SPECIMEN-012	Help Data Toggle	3	TC-SPECIMEN-012	3/3 (100%)	TM-UI	None

Totals: 12 REQs, 55 ACs, 12 Test Cases, 100% Coverage

---

Test Cases

TC-SPECIMEN-001: Specimen Types page access control

Verifies: REQ-SPECIMEN-001 (AC1-4: Access Control, Route, Error Handling)

Method: TM-API, TM-UI

Priority: High

Version: @V3_1_0

Preconditions:

• Two users configured: one SUPER_ADMIN, one non-SUPER_ADMIN (e.g., MANAGER)
• Config Mode available

Test Vectors:

TV	Input	Expected	AC
TV-001	SUPER_ADMIN navigates to Config Mode sidebar "Other Settings"	"Specimen types" link is visible	AC1
TV-002	SUPER_ADMIN accesses /specimens?config_mode=true	Page loads successfully with 200 status	AC3
TV-003	Non-SUPER_ADMIN (MANAGER) navigates to Config Mode sidebar "Other Settings"	"Specimen types" link is not visible	AC2
TV-004	Non-SUPER_ADMIN attempts direct navigation to /specimens?config_mode=true	Access denied	AC4

Expected Results:

• AC1: "Specimen types" link appears in "Other Settings" submenu for SUPER_ADMIN users
• AC2: "Specimen types" link does not appear for non-SUPER_ADMIN users
• AC3: Page served at route /specimens?config_mode=true
• AC4: Non-SUPER_ADMIN direct navigation returns access denied

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-002: Specimen types table display and site scoping

Verifies: REQ-SPECIMEN-002 (AC1-5: Display, Columns, Site Scoping)

Method: TM-API

Priority: High

Version: @V3_1_0

Preconditions:

• User logged in as SUPER_ADMIN
• Site A has specimens: "Plasma" (use_quant=true), "Serum" (use_quant=false)
• Site B has specimen: "CSF" (use_quant=true)

Test Data:

Specimen Name	Use Quantification	Site
Plasma	true	Site A
Serum	false	Site A
CSF	true	Site B

Test Vectors:

TV	Input	Expected	AC
TV-001	GET /api/specimens as Site A user	Returns "Plasma" and "Serum" only	AC1, AC5
TV-002	Verify response structure	Each specimen has specimen_name and use_quant fields	AC2
TV-003	GET /api/specimens for a site with no specimens	Returns empty array	AC3
TV-004	Site A user attempts to access Site B specimen by ID	404 response	AC5
TV-005	GET /api/specimens as Site B user	Returns "CSF" only, not "Plasma" or "Serum"	AC4

Expected Results:

• AC1: All specimens for the user's logged-in site are returned
• AC2: Response includes specimen_name and use_quant fields
• AC3: Empty array returned when no specimens exist for site
• AC4: Specimens from other sites are not returned
• AC5: API queries scoped by user's logged_in_site_id; cross-site access returns 404

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-003: Create new specimen type

Verifies: REQ-SPECIMEN-003 (AC1-6: Add Panel, Validation, Batch Save)

Method: TM-API

Priority: High

Version: @V3_1_0

Preconditions:

• User logged in as SUPER_ADMIN
• Site has no existing specimen named "Nasopharyngeal Swab"
• Site has existing specimen named "Plasma"

Test Data:

Field	Valid Value	Invalid Value
specimen_name	"Nasopharyngeal Swab"	"" (empty), "Plasma" (duplicate)
use_quant	false (default), true	N/A

Test Vectors:

TV	Input	Expected	AC
TV-001	POST /api/specimens with specimen_name: "Nasopharyngeal Swab", use_quant: false	201 Created; specimen returned with generated UUID	AC1, AC2
TV-002	POST /api/specimens with specimen_name: "Nasopharyngeal Swab", use_quant: true	201 Created; specimen has use_quant=true	AC2
TV-003	POST /api/specimens with specimen_name: "Plasma" (already exists)	422 error: Specimen "Plasma" already exists.	AC4, AC5
TV-004	POST /api/specimens with specimen_name: "" (empty)	422 validation error	AC6
TV-005	POST /api/specimens with specimen_name exceeding 255 characters	422 validation error	AC4
TV-006	After successful create, GET /api/specimens	New specimen appears in listing	AC3

Expected Results:

• AC1: New specimen created with provided name and use_quant value
• AC2: Default use_quant is false when not provided; true when explicitly set
• AC3: After save, specimen appears in the table listing
• AC4: Duplicate name returns 422 with descriptive error message
• AC5: Specimen name must be unique per site (case-insensitive)
• AC6: Empty specimen name rejected by validation

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-004: Edit existing specimen type

Verifies: REQ-SPECIMEN-004 (AC1-5: Edit Panel, Working Set, Unsaved Changes)

Method: TM-API, TM-UI

Priority: High

Version: @V3_1_0

Preconditions:

• User logged in as SUPER_ADMIN
• Site has specimen "Plasma" with use_quant=false

Test Vectors:

TV	Input	Expected	AC
TV-001	PUT /api/specimens/{id} with use_quant: true	200 OK; specimen returned with use_quant=true	AC1, AC3
TV-002	PUT /api/specimens/{id} without changing use_quant	200 OK; specimen unchanged	AC2
TV-003	Verify specimen_name is not modifiable via PUT	specimen_name remains "Plasma" regardless of request body	AC1
TV-004	PUT /api/specimens/{id} for specimen belonging to different site	404 response	AC3
TV-005	(UI) Open edit panel, modify use_quant, attempt to close panel	Unsaved changes warning dialog with Save/Discard/Cancel	AC4, AC5

Expected Results:

• AC1: Specimen name is read-only (immutable after creation); only use_quant is editable
• AC2: Confirm Changes button disabled when form is unmodified
• AC3: Confirmed edits tracked in working set for batch save
• AC4: Footer navigation (Next/Previous) allows navigating between pending changes
• AC5: Unsaved changes trigger warning dialog on panel close

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-005: Delete specimen type with association warning

Verifies: REQ-SPECIMEN-005 (AC1-3: Deletion, Association Warning)

Method: TM-API

Priority: High

Version: @V3_1_0

Preconditions:

• User logged in as SUPER_ADMIN
• Site has specimen "Orphan" with no associations (no suffix mappings, test codes, reportings, or combined outcomes)
• Site has specimen "Serum" with an existing suffix mapping association

Test Vectors:

TV	Input	Expected	AC
TV-001	Delete specimen "Orphan" (no associations)	Specimen deleted successfully	AC1
TV-002	Attempt to delete specimen "Serum" (has associations)	Warning displayed indicating downstream impact before confirmation	AC2
TV-003	Confirm deletion of specimen "Serum" after warning	Specimen removed from site configuration	AC3

Expected Results:

• AC1: Deletion available for specimens without blocking constraints
• AC2: When specimen has associations, warning indicates scope of downstream impact
• AC3: After confirmed deletion, specimen removed from site configuration

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-006: Target Name Suffix page access control

Verifies: REQ-SPECIMEN-006 (AC1-4: Access Control, Configuration Gating)

Method: TM-UI

Priority: High

Version: @V3_1_0

Preconditions:

• Two users: SUPER_ADMIN, non-SUPER_ADMIN
• use_sample_type client configuration is configurable per test vector

Test Vectors:

TV	Input	Expected	AC
TV-001	SUPER_ADMIN with use_sample_type = "From Target Suffix", open Config Mode sidebar "Other Settings"	"Target Name Suffix to Specimen" link visible	AC1, AC2
TV-002	SUPER_ADMIN with use_sample_type != "From Target Suffix", open Config Mode sidebar	"Target Name Suffix to Specimen" link not visible	AC2
TV-003	Non-SUPER_ADMIN with use_sample_type = "From Target Suffix", open Config Mode sidebar	"Target Name Suffix to Specimen" link not visible	AC3
TV-004	SUPER_ADMIN accesses /target-name-suffix-to-specimen?config_mode=true with correct config	Page loads successfully	AC4

Expected Results:

• AC1: Link appears in "Other Settings" submenu for SUPER_ADMIN users
• AC2: Link only visible when use_sample_type equals "From Target Suffix"
• AC3: Non-SUPER_ADMIN users cannot see the link regardless of configuration
• AC4: Page served at route /target-name-suffix-to-specimen?config_mode=true

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-007: Target suffix mapping table display

Verifies: REQ-SPECIMEN-007 (AC1-5: Display, Site Scoping)

Method: TM-API

Priority: High

Version: @V3_1_0

Preconditions:

• User logged in as SUPER_ADMIN
• Site A has suffix mappings: "NPS" -> "Nasopharyngeal Swab", "PL" -> "Plasma"
• Site B has suffix mapping: "SER" -> "Serum"
• use_sample_type = "From Target Suffix"

Test Data:

Target Name Suffix	Specimen Name	Site
NPS	Nasopharyngeal Swab	Site A
PL	Plasma	Site A
SER	Serum	Site B

Test Vectors:

TV	Input	Expected	AC
TV-001	GET /api/target-name-suffix-to-specimen as Site A user	Returns mappings "NPS" and "PL" with specimen names	AC1
TV-002	Verify response structure	Each mapping has target_name_suffix (uppercase) and specimen_name	AC2
TV-003	GET /api/target-name-suffix-to-specimen for site with no mappings	Returns empty result	AC3
TV-004	GET /api/target-name-suffix-to-specimen as Site B user	Returns "SER" only, not "NPS" or "PL"	AC4
TV-005	Verify suffix uniqueness constraint	(target_name_suffix, site_id) is unique at database level	AC5

Expected Results:

• AC1: All suffix-to-specimen mappings for user's site returned
• AC2: Suffixes displayed in uppercase; specimen names shown (or "-" if empty)
• AC3: Empty result when no mappings exist for site
• AC4: Data scoped to user's site; other sites' mappings not returned
• AC5: Unique constraint on (target_name_suffix, site_id) at database level

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-008: Create target name suffix mapping

Verifies: REQ-SPECIMEN-008 (AC1-6: Add Panel, Suffix Validation, Inline Specimen Creation)

Method: TM-API

Priority: High

Version: @V3_1_0

Preconditions:

• User logged in as SUPER_ADMIN
• Site has specimen "Plasma"
• Site has existing suffix mapping "NPS" -> "Nasopharyngeal Swab"
• use_sample_type = "From Target Suffix"

Test Data:

Field	Valid Value	Invalid Value
target_name_suffix	"PL"	"NPS" (duplicate), "" (empty)
specimen_id	UUID of "Plasma"	null

Test Vectors:

TV	Input	Expected	AC
TV-001	POST suffix mapping with suffix "pl" and specimen "Plasma"	Mapping created with suffix stored as "PL" (uppercase)	AC1, AC3
TV-002	POST suffix mapping with suffix "nps" (case-insensitive duplicate of existing "NPS")	Validation error: "Suffix should be unique (case-insensitive)"	AC4, AC5
TV-003	POST suffix mapping with empty suffix	Validation error: required field	AC6
TV-004	Create a new specimen "CSF" via inline creation, then use it in a new mapping	Specimen created; mapping created with "CSF" as specimen	AC2
TV-005	After successful mapping creation, GET /api/target-name-suffix-to-specimen	New mapping appears in listing	AC1
TV-006	POST suffix mapping with valid data	Success message returned; table refreshes	AC1

Expected Results:

• AC1: Mapping created with suffix and specimen association
• AC2: Inline specimen creation supported without leaving the page
• AC3: All suffixes normalized to UPPERCASE before storage
• AC4: Duplicate suffix (case-insensitive) rejected with validation error
• AC5: Error message: "Suffix should be unique (case-insensitive)"
• AC6: Missing required fields prevented by validation

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-009: Edit target suffix mapping

Verifies: REQ-SPECIMEN-009 (AC1-6: Edit Panel, Batch Save, Unsaved Changes)

Method: TM-API

Priority: High

Version: @V3_1_0

Preconditions:

• User logged in as SUPER_ADMIN
• Site has suffix mappings: "NPS" -> "Nasopharyngeal Swab", "PL" -> "Plasma"
• Site has specimen "Serum" available for reassignment
• use_sample_type = "From Target Suffix"

Test Vectors:

TV	Input	Expected	AC
TV-001	PUT /api/target-name-suffix-to-specimen changing "NPS" mapping from "Nasopharyngeal Swab" to "Serum"	200 OK; "NPS" now maps to "Serum"	AC1, AC4
TV-002	Verify suffix value is immutable during edit	Target name suffix "NPS" remains unchanged in response	AC2
TV-003	PUT with specimen_id set to null	Validation error: specimen is required	AC3
TV-004	PUT with batch of modified mappings	All modified mappings updated in single API call	AC4
TV-005	PUT attempting to create suffix collision (case-insensitive)	Backend validation rejects duplicate suffix	AC4
TV-006	(UI) Open edit panel, modify specimen, attempt to close	Unsaved changes warning with Save/Discard/Cancel	AC5, AC6

Expected Results:

• AC1: Suffix value displayed as disabled (read-only) field
• AC2: Specimen editable via dropdown selector (required)
• AC3: Confirm Changes button disabled if form is invalid or unmodified
• AC4: Batch save sends all modified mappings in single PUT call; backend validates for duplicate suffixes (case-insensitive)
• AC5: On success: success message displayed, table refreshes
• AC6: Closing edit panel with unsaved modifications triggers warning dialog

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-010: Delete target suffix mapping

Verifies: REQ-SPECIMEN-010 (AC1-4: Confirmation, Deletion, Cancellation)

Method: TM-API

Priority: High

Version: @V3_1_0

Preconditions:

• User logged in as SUPER_ADMIN
• Site A has suffix mapping "NPS" -> "Nasopharyngeal Swab"
• Site B has a different suffix mapping
• use_sample_type = "From Target Suffix"

Test Vectors:

TV	Input	Expected	AC
TV-001	DELETE /api/target-name-suffix-to-specimen/{id} for own site mapping	HTTP 204 No Content; mapping removed	AC2
TV-002	After deletion, GET /api/target-name-suffix-to-specimen	Deleted mapping no longer in listing	AC2
TV-003	DELETE /api/target-name-suffix-to-specimen/{id} for mapping belonging to different site	404 response	AC2
TV-004	(UI) Click delete, cancel confirmation dialog	Mapping remains unchanged	AC4

Expected Results:

• AC1: Confirmation dialog displayed with suffix name before deletion
• AC2: Confirmed deletion sends DELETE request; backend verifies site ownership (404 on mismatch); HTTP 204 on success
• AC3: After deletion, table refreshes and selection clears if deleted mapping was selected
• AC4: Cancelling the dialog leaves the mapping unchanged

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-011: Automatic specimen assignment via suffix matching during import

Verifies: REQ-SPECIMEN-011 (AC1-4: Matching Logic, Downstream Effects)

Method: TM-API

Priority: High

Version: @V3_1_0

Preconditions:

• User logged in as SUPER_ADMIN
• use_sample_type = "From Target Suffix"
• Site has suffix mappings: "NPS" -> "Nasopharyngeal Swab", "PL" -> "Plasma"
• Mix configured with targets that will match imported target names
• Reporting cut-offs or combined outcomes configured for specimen-specific behavior

Test Data:

Target Name in Runfile	Configured Suffix	Expected Specimen
HIV-NPS	NPS	Nasopharyngeal Swab
COVID-PL	PL	Plasma
HIV-IC	(none match)	No specimen assigned

Test Vectors:

TV	Input	Expected	AC
TV-001	Import runfile containing target "HIV-NPS" with suffix mapping "NPS" -> "Nasopharyngeal Swab"	Observations for "HIV-NPS" associated with specimen type "Nasopharyngeal Swab"	AC1, AC2
TV-002	Import runfile containing target "HIV-IC" with no matching suffix	No specimen type assigned to "HIV-IC" observations	AC3
TV-003	Import runfile with target "COVID-PL"; suffix matching is case-insensitive against uppercase-stored suffix	Observations for "COVID-PL" associated with specimen type "Plasma"	AC2
TV-004	Configure specimen-specific reporting cut-off for "Nasopharyngeal Swab"; import runfile with matching target	Specimen-specific reporting configuration applied instead of "Any" default	AC4

Expected Results:

• AC1: System compares each target name against all configured suffixes for the site during import
• AC2: Matching performed against uppercase-normalized suffix; matched targets assigned associated specimen type
• AC3: When no suffix matches, no specimen type is assigned (existing behavior preserved)
• AC4: Specimen-specific configuration takes precedence over non-specimen ("Any") configuration when both exist

Automation Status: Planned

Jira: BT-5894

---

TC-SPECIMEN-012: Help data toggle on Target Suffix page

Verifies: REQ-SPECIMEN-012 (AC1-3: Feature-Flag Gating, Toggle Behavior)

Method: TM-UI

Priority: Low

Version: @V3_1_0

Preconditions:

• User logged in as SUPER_ADMIN
• use_sample_type = "From Target Suffix"
• help_items feature flag is configurable per test vector

Test Vectors:

TV	Input	Expected	AC
TV-001	Navigate to Target Suffix page with help_items feature flag enabled	Help data toggle is visible on the page	AC1
TV-002	Activate the help data toggle	Contextual help information displayed	AC2
TV-003	Deactivate the help data toggle	Help content hidden	AC3

Expected Results:

• AC1: Help data toggle visible only when help_items feature flag is enabled
• AC2: Activating toggle displays contextual help information
• AC3: Deactivating toggle hides help content

Automation Status: Planned

Jira: BT-5894

---

Traceability

REQ-to-TC Cross Reference

REQ ID	Test Cases	Coverage
REQ-SPECIMEN-001	TC-SPECIMEN-001	4/4 AC
REQ-SPECIMEN-002	TC-SPECIMEN-002	5/5 AC
REQ-SPECIMEN-003	TC-SPECIMEN-003	6/6 AC
REQ-SPECIMEN-004	TC-SPECIMEN-004	5/5 AC
REQ-SPECIMEN-005	TC-SPECIMEN-005	3/3 AC
REQ-SPECIMEN-006	TC-SPECIMEN-006	4/4 AC
REQ-SPECIMEN-007	TC-SPECIMEN-007	5/5 AC
REQ-SPECIMEN-008	TC-SPECIMEN-008	6/6 AC
REQ-SPECIMEN-009	TC-SPECIMEN-009	6/6 AC
REQ-SPECIMEN-010	TC-SPECIMEN-010	4/4 AC
REQ-SPECIMEN-011	TC-SPECIMEN-011	4/4 AC
REQ-SPECIMEN-012	TC-SPECIMEN-012	3/3 AC

API Endpoint Coverage

Endpoint	Method	Test Cases
/api/specimens	GET	TC-SPECIMEN-002, TC-SPECIMEN-003
/api/specimens	POST	TC-SPECIMEN-003
/api/specimens/{specimen}	PUT	TC-SPECIMEN-004
/api/target-name-suffix-to-specimen	GET	TC-SPECIMEN-007, TC-SPECIMEN-008
/api/target-name-suffix-to-specimen	POST	TC-SPECIMEN-008
/api/target-name-suffix-to-specimen	PUT	TC-SPECIMEN-009
/api/target-name-suffix-to-specimen/{id}	DELETE	TC-SPECIMEN-010

Dependencies

Test Case	Depends On
TC-SPECIMEN-006	use_sample_type client configuration set to "From Target Suffix"
TC-SPECIMEN-007 through TC-SPECIMEN-010	TC-SPECIMEN-006 (page access requires configuration)
TC-SPECIMEN-011	Configured suffix mappings (TC-SPECIMEN-008), import pipeline availability
TC-SPECIMEN-012	help_items feature flag enabled

---

Notes

• All specimen management capabilities are new in v3.1.0. Every test case carries the @V3_1_0 version tag.
• The specimen API routes (GET/POST/PUT) do not have explicit user-type middleware in the route definition; access control for the CRUD UI is enforced at the Config Mode sidebar level (SUPER_ADMIN only). API-level tests should verify behavior with authenticated users of appropriate role.
• The suffix matching logic (TC-SPECIMEN-011) integrates with the runfile import pipeline. Testing requires a complete import flow -- suffix mappings must be configured before importing a runfile that exercises the matching.
• REQ-SPECIMEN-005 (delete) -- the SRS mentions association warnings but the controller code (SpecimensController.php) does not currently expose a delete endpoint. The delete behavior may be handled client-side or via a separate endpoint not yet present in v3.0.1 code. Tests should be validated against v3.1.0 code.
• Specimens created via inline creation on the Target Suffix page (TC-SPECIMEN-008 TV-004) use the same POST /api/specimens endpoint as the dedicated Specimen Types page, so validation rules are identical.