@ngocsangairvds/vsaf 3.1.0 → 3.1.2

package/.claude/skills/vsaf-test/SKILL.md

@@ -1,65 +1,85 @@
 ---
 name: vsaf-test
-description: Viết tài liệu testcase từ SRS. Dùng sau /vsaf-doc và trước /vsaf-build. Test cases dựa trên spec, không dựa trên code hiện tại.
+description: "Two modes: (1) generate testcases from SRS — used after /vsaf-doc-srs and before /vsaf-build; (2) 'run' — execute tests, verify coverage, write results. Test cases are based on spec, not on code."
 ---
 
 # VSAF Test
 
-## Mục tiêu
-Tạo tài liệu testcase coverage đầy đủ từ SRS để làm contract cho implementation.
+## Mode distinction
 
-## Điều kiện tiên quyết
-- Đã chạy `/vsaf-doc`
-- Có file SRS trong `docs/project/srs/`
+| Command | Mode | Goal |
+|---------|------|------|
+| `/vsaf-test <path/to/srs>` | **generate** | Generate testcase docs from SRS |
+| `/vsaf-test run <path/to/testcases>` | **run** | Execute tests, verify coverage, write results file |
 
-## Các bước thực hiện
+---
+
+# Mode 1: Generate — Generate testcases from SRS
+
+## Goal
+Create comprehensive testcase coverage documentation from SRS to serve as a contract for implementation.
+
+## Prerequisites
+- Already ran `/vsaf-doc-prd` and `/vsaf-doc-srs`
+- SRS file exists in `docs/project/srs/`
 
-### Bước 1 — Sinh test cases từ SRS (BMAD qa)
-- Dùng skill `bmad-qa-generate-e2e-tests` với SRS file trong `docs/project/srs/` làm input
-- Test cases phải cover: happy path, edge cases, error cases, NFRs
-- Nguồn gốc: từ FRs/NFRs trong SRS — KHÔNG dựa trên implementation
+## Steps
 
-### Bước 2 — Hunt edge cases (BMAD edge case hunter)
-- Dùng skill `bmad-review-edge-case-hunter` với SRS + testcases đã sinh
-- Tìm: boundary conditions, race conditions, empty/null inputs, overflow, concurrent access
-- Bổ sung test cases cho mọi edge case chưa cover
-- Mục tiêu: không có unhandled edge case nào lọt qua
+### Step 0 — Find existing test patterns (GitNexus)
+- Use `gitnexus_query({query: "test patterns for <feature domain>"})` to see how the project currently tests
+- Reference existing patterns to generate testcases consistent with the codebase
 
-### Bước 3 — Đối chiếu coverage
-- So sánh test cases với FR/NFR trong SRS
-- Mỗi FR/NFR phải có ít nhất 1 test case tương ứng
-- Ghi nhận gaps nếu có
+### Step 1 — Generate test cases from SRS (BMAD qa)
+- Use skill `bmad-qa-generate-e2e-tests` with the SRS file in `docs/project/srs/` as input
+- Test cases must cover: happy path, edge cases, error cases, NFRs
+- Source: from FRs/NFRs in SRS — NOT based on implementation
 
-### Bước 4 — Xuất traceability matrix
-- Tạo bảng mapping `FR/NFR -> Testcase ID`
-- Mỗi testcase có: input, expected output, pass/fail criteria
+### Step 2 — Hunt edge cases (BMAD edge case hunter)
+- Use skill `bmad-review-edge-case-hunter` with SRS + generated testcases
+- Look for: boundary conditions, race conditions, empty/null inputs, overflow, concurrent access
+- Add test cases for all uncovered edge cases
+- Goal: no unhandled edge case slips through
 
-### Bước 5 — Lưu tài liệu testcase
-- Lưu testcase vào `docs/project/testcases/[feature].md`
+### Step 3 — Cross-check coverage
+- Compare test cases against FR/NFR in SRS
+- Each FR/NFR must have at least 1 corresponding test case
+- Document gaps if any
+
+### Step 4 — Export traceability matrix
+- Create a mapping table `FR/NFR -> Testcase ID`
+- Each testcase has: input, expected output, pass/fail criteria
+
+### Step 5 — Save testcase document
+- Save testcases to `docs/project/testcases/[feature].md`
 - Format:
 
 ```markdown
 ## Testcases: [feature]
 
+### Traceability Matrix
+| FR/NFR ID | Testcase IDs | Coverage |
+|-----------|-------------|----------|
+| FR-001    | TC-001, TC-002 | ✓     |
+
 ### Unit Tests
-| Test case | Input | Expected | Status |
-|-----------|-------|----------|--------|
-| ...       | ...   | ...      | [ ]    |
+| Test case | FR/NFR | Input | Expected | Status |
+|-----------|--------|-------|----------|--------|
+| TC-001    | FR-001 | ...   | ...      | [ ]    |
 
 ### Integration Tests
-| ...       | ...   | ...      | [ ]    |
+| ...       | ...    | ...   | ...      | [ ]    |
 
 ### Edge Cases
-| ...       | ...   | ...      | [ ]    |
+| ...       | ...    | ...   | ...      | [ ]    |
 ```
 
-### Bước 6 — Implementation readiness gate (BMAD)
-- Dùng skill `bmad-check-implementation-readiness` để validate toàn bộ artifacts
-- Kiểm tra: SRS đầy đủ? Testcases cover hết FRs/NFRs? Architecture align?
-- Nếu **PASS**: hiển thị `✓ Implementation ready — proceed to /vsaf-build`
-- Nếu **FAIL**: liệt kê gaps cần fix trước khi build, KHÔNG cho tiếp
+### Step 6 — Implementation readiness gate (BMAD)
+- Use skill `bmad-check-implementation-readiness` to validate all artifacts
+- Check: SRS complete? Testcases cover all FRs/NFRs? Architecture aligned?
+- If **PASS**: display `✓ Implementation ready — proceed to /vsaf-build`
+- If **FAIL**: list gaps that need fixing before build, DO NOT proceed
 
-### Bước 7 — Output cho user
+### Step 7 — Output to user
 ```
 ## Testcase Summary: [feature]
 
@@ -72,10 +92,108 @@ Files:
 - docs/project/testcases/[feature].md
 
 ## Next step
-[Nếu PASS]: Chạy /vsaf-build <path/to/srs> <path/to/testcases>
-[Nếu FAIL]: Fix gaps listed above, then re-run /vsaf-test
+[If PASS]: Run /vsaf-build <path/to/prd> <path/to/srs> <path/to/testcases>
+[If FAIL]: Fix gaps listed above, then re-run /vsaf-test
+```
+
+---
+
+# Mode 2: Run — Execute tests + write results
+
+## Goal
+Execute the full test suite, verify coverage matches changed code, write a structured results file. The results file is a required input for `/vsaf-ship`.
+
+## Prerequisites
+- Already ran `/vsaf-build` — code implementation is complete
+- Testcase file exists at `docs/project/testcases/[feature].md`
+
+## Steps
+
+### Step 1 — Re-read testcase file
+- Re-read the testcase file, confirm all tests are present
+- Cross-check with traceability matrix: each FR/NFR must have at least 1 test
+
+### Step 2 — Execute test suite
+- Run all tests: unit + integration + e2e
+- Use the project test runner (Maven/Gradle/npm/etc.)
+- Record output for each test case
+
+### Step 3 — Map results back to FR/NFR
+- Record pass/fail for each testcase
+- Map results back to the traceability matrix: which FR/NFR passed, which have not
+
+### Step 4 — Verify coverage matches changed code (GitNexus)
+- Run `gitnexus_detect_changes({scope: "compare", base_ref: "main"})`
+- Compare the list of changed files/symbols with the list of tested files/symbols
+- Flag any changed file/symbol that does NOT have test coverage
+
+### Step 5 — Architectural constraint check (GitNexus, optional)
+- Run `gitnexus_shape_check` to validate no architectural constraints are violated
+- Record constraint compliance results in the results file
+
+### Step 6 — Write results file
+- Save results to `docs/project/testcases/[feature]-results.md`
+- Format:
+
+```markdown
+## Test Results: [feature]
+Date: [YYYY-MM-DD]
+
+### Summary
+| Metric | Value |
+|--------|-------|
+| Total tests | [N] |
+| Passed | [N] |
+| Failed | [N] |
+| Pass rate | [%] |
+| FR/NFR coverage | [X/Y] ([%]) |
+| Untested changes | [N files/symbols] |
+| Shape check | [PASS / SKIP / FAIL] |
+
+### Results by FR/NFR
+| FR/NFR ID | Tests | Passed | Failed | Status |
+|-----------|-------|--------|--------|--------|
+| FR-001    | 3     | 3      | 0      | ✓      |
+| FR-002    | 2     | 1      | 1      | ✗      |
+
+### Failed Tests
+| Test case | FR/NFR | Expected | Actual | Notes |
+|-----------|--------|----------|--------|-------|
+
+### Untested Changes (from detect_changes)
+| File/Symbol | Change type | Test coverage |
+|-------------|------------|---------------|
+
+### Shape Check Results
+[Output from gitnexus_shape_check, or "Skipped"]
+```
+
+### Step 7 — Ship gate
+- **PASS** if:
+  - All FR/NFR have at least 1 test PASS
+  - No untested changes (or reason has been explained)
+  - Shape check has no violations
+- **FAIL** if:
+  - Any FR/NFR has 0 passing tests -> **blocks ship**
+  - Untested changes detected without justification -> **blocks ship**
+  - Shape check violations -> **blocks ship**
+- Display:
+
+```
+## Test Run Results: [feature]
+
+- Pass rate: [X/Y] ([%])
+- FR/NFR coverage: [X/Y] ([%])
+- Untested changes: [N] — [CLEAR / BLOCKED]
+- Shape check: [PASS / SKIP / FAIL]
+- Ship gate: [PASS ✓ / FAIL ✗]
+
+Results file: docs/project/testcases/[feature]-results.md
+
+## Next step
+[If PASS]: Run /vsaf-ship
+[If FAIL]: Fix failures above, then re-run /vsaf-test run
 ```
 
-## Lưu ý
-- Không đánh dấu implementation done ở bước này
-- Nếu coverage thiếu cho FR/NFR quan trọng: quay lại cập nhật SRS trước khi build
+## Notes
+- Results file is a required input for `/vsaf-ship` — no results = no ship