Test Case Documentation And Unit Test Handling

Requirement-first workflow

1. Extract identifiers, actors, actions, entities, state transitions, validations, and important observable outcomes from the requirement or use case.
2. Search the codebase for routes, controllers, services, DTOs, enums, status constants, repository methods, events, logs, UI labels, and text that match the requirement.
3. Trace the full relevant flow from the entry point to downstream collaborators. Do not stop at the first file match.
4. Build a scoped inventory of directly relevant units: controller methods, service methods, validators, guards, helpers, mappers, repository/query methods, UI handlers, and other functions with business logic.
5. Include subordinate methods and side-path logic that materially affect the use case, such as permission checks, validation helpers, state-transition branches, duplicate detection, repository lookups, logging, audit trails, notifications, and quota or usage tracking.
6. Test every directly relevant function or method that contains branching, validation, permission checks, state changes, calculations, mapping, or other observable business outcomes.
7. Explicitly note thin wrappers or purely declarative code that were scanned but intentionally skipped.
8. State the assumption and continue when multiple plausible implementations exist instead of stalling.

Unit test workflow

1. Analyze behavior, branches, preconditions, edge cases, exceptions, state changes, and boundaries for each in-scope function.
2. Match the existing project test framework when it is discoverable. Otherwise choose a conventional default for the language and note the assumption briefly.
3. Cover Normal (N), Abnormal (A), and Boundary (B) scenarios for each directly relevant function or method.
4. Mock downstream dependencies so the tests isolate the unit under test.
5. Assert returns, exceptions, state transitions, repository writes, emitted events, logs, visibility changes, notifications, permission outcomes, and other observable effects when relevant.
6. Distinguish between test assertions and traceability-matrix content: mocked method calls and internal collaboration checks may be asserted in tests, but they should not be listed in the Excel matrix unless the user explicitly asks for internal side-effect mapping.
7. Group the output by function or file when the request started from a use case so the coverage stays readable.
8. For use-case requests, split coverage by function rather than collapsing the entire use case into one default matrix.
9. For use-case requests, prefer a deep suite that covers the full in-scope chain rather than a shallow single-method sample.
10. Output raw unit test code only when the user explicitly asks for it.
11. When matching automated tests already exist in the repository, run them before finalizing the workbook instead of defaulting to Untested.
12. Prefer real execution evidence from the nearest relevant test files so the workbook can show Passed or Failed rows whenever the repository already proves the behavior.
13. Never mark a UTCID as Passed or Failed without executed evidence that reasonably maps to that case; do not fabricate a best-case 100% pass.

Documentation workflow

• After writing or locating the tests, create the traceability documentation as a real .xlsx workbook by default.
• Do not create companion Markdown, JSON, TXT, or other note files unless the user explicitly asks for them.
• If a helper JSON payload is needed to build the workbook, prefer piping it via stdin. If a temp file is used, delete it after generation.
• When the user provides a matrix example/template, match that structure and wording as closely as possible, even if it implies a single consolidated use-case sheet instead of one sheet per function.
• For unit-test traceability matrices, keep the workbook content limited to the matrix itself plus the normal header/summary rows.
• Only output raw unit test code, discovery summaries, assumptions, or implementation-gap prose when the user explicitly asks for them.
• Default to one workbook file for the whole requested scope, with multiple tabs inside that file when multiple functions are involved.
• Keep Cover, Function List, Test Report, and the function tabs in that same file unless the user explicitly asks for a stripped workbook.
• Do not create cumulative versioned workbook chains unless the user explicitly asks for that older workflow again.

Function-first rules

• When the user gives a feature or a use case, first identify how many directly relevant logic-bearing functions implement it.
• Create test cases per function.
• Do not assume 1 sheet = 1 use case.
• Default to 1 sheet = 1 function.
• It is acceptable for one workbook to contain many functions from multiple use cases when they belong to the same feature or requested scope.
• Thin wrappers with no meaningful business logic may be documented as scanned and skipped instead of getting a dedicated sheet.
• For unit-test requests, use the actual method name as the function identity. Route text is supporting context, not the function name.
• When a human-readable label is needed, split the method name into title case, for example processRescheduleRequest -> Process Reschedule Request.

Matrix rules

• Create one UTCID per test case: UTCID01, UTCID02, UTCID03, and so on.
• Use O to mark which conditions, confirms, and results apply to each UTCID.
• Keep the section order fixed: header section, summary section, matrix header, condition rows, confirm rows, result rows.
• Keep every CSV rectangular.
• Match the user's template ordering and wording as closely as possible when an example format is provided.

Header section rules

• Include Function Code, Function Name, Created By, Executed By, Lines of code, Lack of test cases, and Test requirement.
• When documenting by function, use the actual function identifier as Function Code. If there is also a UC ID, keep that in the requirement text, feature context, or workbook grouping instead of replacing the function identity.
• Use the actual function or method name for Function Name.
• Leave Executed By blank unless execution ownership is known.
• Count only the function or method under test for Lines of code.
• Default Lack of test cases to 0 when the suite is intended to be complete. If known gaps remain, use the number of missing cases.
• Write Test requirement as a concise function-specific description of what is verified.

Summary section rules

• Include Passed, Failed, Untested, N, A, B, and Total Test Cases.
• Prefer populated execution counts from real test runs whenever matching tests are available locally.
• If tests were not actually executed, set Passed = 0, Failed = 0, and Untested = Total Test Cases.
• Count N, A, and B from the generated tests for that function or module.

Matrix rows

• Under Condition, include required preconditions and one row per distinct input value or state used in the tests.
• Write Precondition rows in a detailed matrix style: one concrete setup fact per row, not one broad summary sentence.
• Split actor/auth facts, ownership facts, current status facts, assignment facts, and related-record existence into separate rows when they independently matter.
• Prefer explicit wording such as Authenticated client owns request "req-1" and Request "req-1" is currently "DRAFT" over vague text such as valid editable request exists.
• Reuse the exact same row text across UTC columns when the same precondition is shared, so the mark matrix stays aligned and readable.
• Use exact IDs, role names, and enum/state values in precondition rows when the branch depends on them.
• Treat Request / Input Variable rows as the actual values passed into the function under test, not the route template.
• Prefer rows such as id = "audit-1", requestId = "req-1", page = 2, limit = 20, and reason = "Need reconsideration" over rows that repeat /audit-logs/:id or POST /leave/requests.
• For DTO/object inputs, list the meaningful body/query fields that the executed test actually uses instead of one vague request or body row.
• Under Condition, prefer only Precondition, Action, Request status or State, and Input Variable.
• Under Confirm, include only expected returns and exceptions.
• Write Exception rows with the concrete failure reason when the code enforces a business rule. Prefer Dispute "dispute-1" cannot be closed while hearing is pending or Email "[email protected]" already exists over generic labels such as Bad Request or Unprocessable Entity.
• Use plain HTTP/status-only labels only for framework-level validation failures when no more precise application message exists.
• Keep each materially different failure reason on a separate exception row so reviewers can distinguish validation errors, not-found branches, permission denials, and business-state violations.
• When useful, include the exception class together with the business message, for example ConflictException: Email "[email protected]" already exists.
• When the matrix format includes Log message, populate it with specific quoted messages. Prefer real asserted logger output; otherwise use deterministic executed-case messages that clearly describe the branch outcome.
• Do not add Side effect, Message, Log, Audit, Quota, Notification, or other collaborator/internal rows unless the user explicitly asks for them.
• Put failure outcomes under Exception, not under Return.
• Use Return only for successful or direct returned values and primary state outputs. When a use case mainly changes status, values like status = PUBLIC_DRAFT are valid Return rows.
• Under Result, include Type(N : Normal, A : Abnormal, B : Boundary), Passed/Failed, Executed Date, and Defect ID.
• When a UTCID can be traced to an executed repository test, mark it Passed or Failed based on that real result instead of leaving it Untested.
• Use Untested for Passed/Failed unless the tests were actually executed.
• Use MM/DD for Executed Date only when the date is known. Otherwise leave it blank.
• Leave Defect ID blank unless the user provides one or explicitly asks for mock IDs.

Workbook workflow

• When the workspace is writable, create a real .xlsx workbook as the primary output whenever the user asks for documentation, a matrix, Excel output, or a template like an .xlsx screenshot.
• Use the bundled script at scripts/generate_traceability_xlsx.ps1 to build the workbook from a rectangular row matrix serialized as JSON.
• Default output location: docs/unit/fn-XX-<function-slug>-unit-test.xlsx (or a feature-scoped name when the request covers many functions).
• Prefer in-memory JSON to avoid creating *-input.json artifacts:

$json = @'
{ "sheetName": "FN-01 Traceability", "rows": [ ["..."], ["..."] ] }
'@
& .codex/skills/test-case-documentation-and-unit-test-handling/scripts/generate_traceability_xlsx.ps1 -InputJsonText $json -OutputPath <output.xlsx> -Overwrite

• Default workbook location:
  1. <workspace>/docs/unit/<function-code>-unit-test.xlsx when a docs/unit folder exists
  2. otherwise <workspace>/<function-code>-unit-test.xlsx
• Default workbook shape:
  1. one workbook for the requested feature or scope when multiple functions are involved
  2. one sheet per function by default
  3. use one-sheet-per-use-case when the user explicitly asks for that layout or provides a concrete single-sheet example/template to follow
  4. extra workbooks are only needed when the user explicitly asks for separate files
• When the workbook contains multiple function tabs, keep them together in that one file instead of generating many sibling workbooks.
• Preserve Cover, Function List, and Test Report in the same workbook by default.
• Do not leave helper build artifacts or companion explanation files in the workspace unless the user explicitly asks for them.
• If PowerShell execution policy blocks the script, rerun it with powershell -NoProfile -ExecutionPolicy Bypass -File ....
• Always mention the absolute workbook path in the final response.
• If workbook creation is impossible, explain why briefly and still provide the CSV or Markdown matrix in the response.
• Read a real sample tab from the target workbook/template first and preserve its column widths, hidden columns, merged cells, row heights, print area, margins, and orientation. Do not improvise a new sheet geometry.
• Keep the used range compact. Do not paint styles into hundreds of blank rows or extra columns, because that creates empty space and page-width issues when the user opens the file.
• Preserve hidden spacer columns from the sample tab instead of turning them into visible colored columns.
• Avoid introducing stray fill colors or spacing blocks that are not present in the source tab.
• Populate header/summary cells fully:
  • Lines of code may be approximate but must not be blank
  • Lack of test cases should normally be 0 for a complete batch
  • Passed, Failed, Untested, N/A/B, and Total Test Cases should prefer Excel formulas like COUNTIF, COUNTA, and SUM over hardcoded counts
• If the template uses sheet formulas to pull Function Code or Function Name from Function List, preserve that formula style.

Output defaults

• Honor requests for only tests or only documentation when the user explicitly asks for that.
• Default to returning only the .xlsx workbook path (and nothing else) unless the user explicitly asks for unit test code, raw matrices, or helper artifacts.
• Pass stage (completion gate): the final answer returns only the absolute path to the .xlsx workbook under docs/unit/, and no helper files (JSON inputs, scratch notes) are left in docs/.
• When the user gives a requirement or use case, do not ask for code first if the repository is available. Search the codebase, find the relevant implementation, scan the flow, and proceed.
• When the user gives a requirement or use case and relevant test files already exist, run the closest matching test scope before finalizing the workbook so the result rows reflect actual execution.
• When the user gives a requirement or use case, default to deep coverage across all directly relevant methods and functions that implement the flow, then document them function by function.
• When no implementation can be found, say what is missing and provide only the highest-confidence documentation draft instead of inventing runnable tests. If the user requested Excel output, create a clearly marked draft workbook only when the assumptions are explicit.
• If the user clarifies that they want unit tests rather than integration tests, prefer direct method-level tests with mocks and metadata/pipe checks. Do not default to supertest route execution unless the user explicitly asks to validate routing behavior.