lcbp3/specs/300-others/303-frontend-test-coverage/spec.md

Feature Specification: Frontend Test Coverage — Phased Improvement

Feature Branch: 303-frontend-test-coverage Created: 2026-06-13 Status: Draft Category: 300 - Others (Quality Improvement)

Background

รายงาน Code Coverage ของ Frontend (Istanbul.js) ณ วันที่ 2026-06-13 แสดงผลดังนี้:

Metric	Current	Total
Statements	13.54%	679/5,012
Branches	7.80%	301/3,857
Functions	13.72%	253/1,844
Lines	13.84%	656/4,738

โฟลเดอร์ที่มี Coverage > 0% อยู่แล้ว:

Folder	Statements
hooks	30.46%
hooks/ai	44.11%
components/ui	31.69%
components/common	26.66%
components/response-code	26.41%
components/correspondences	21.27%
lib/services	16.64%
components/workflows	15.38%
components/ai	23.7%

โฟลเดอร์ที่เป็น 0% และมีขนาดใหญ่ที่สุด (เรียงตามจำนวน statements):

Folder	Statements
components/rfas	0/254
components/numbering	0/186
components/admin	0/123
components/drawings	0/106
components/layout	0/146
components/workflow	0/110
components/admin/ai	0/278
components/transmittal	0/66
lib/api	1/261

---

User Scenarios & Testing (mandatory)

User Story 1 — Phase 1: ยก Coverage จาก 13% → 30% (Priority: P1)

ทีมพัฒนาสามารถรันคำสั่งทดสอบและเห็นตัวเลข Statement Coverage รวมของ Frontend ที่ไม่ต่ำกว่า 30% โดยส่วนที่ถูกเพิ่มการทดสอบในระยะนี้คือ:

• hooks/ (ทุก custom hook)
• lib/services/ (service functions ที่ใช้บ่อยที่สุด)
• components/correspondences/ (component หลักของระบบ)

Why this priority: hooks และ services เป็น Business Logic Layer ที่ส่งผลกระทบสูงสุดต่อความถูกต้องของระบบ DMS ทั้งหมด

Independent Test: รัน npm run test:cov แล้วดูผลรวม Statements Coverage ≥ 30%

Acceptance Scenarios:

1. Given ระบบมี Statement Coverage 13.54%, When ทีมเขียน Test สำหรับ hooks/ และ lib/services/ ครอบคลุมกรณีหลัก (happy path + error path), Then Statement Coverage รวมขึ้นเป็นอย่างน้อย 30%
2. Given มี Custom Hook ที่ใช้ดึงข้อมูล Correspondences, When เขียน test ครอบ success + error state, Then hook นั้นมี coverage ≥ 70%
3. Given มี Service function ที่ทำ API call, When เขียน test ด้วย mock และ assert ผลลัพธ์, Then function นั้นมี coverage ≥ 70%

---

User Story 2 — Phase 2: ยก Coverage จาก 30% → 50% (Priority: P2)

ทีมพัฒนาสามารถรันคำสั่งทดสอบและเห็นตัวเลข Statement Coverage รวมที่ไม่ต่ำกว่า 50% โดยระยะนี้เพิ่มการทดสอบในส่วน:

• components/rfas/ (เอกสาร RFA — critical business feature)
• components/numbering/ (ระบบเลขที่เอกสาร)
• components/drawings/ (Shop Drawing / Contract Drawing)
• lib/api/ (API client functions)
• components/auth/ (authentication flow)

Why this priority: RFA และ Document Numbering เป็น Core Business Process ที่สร้างรายได้และมีความเสี่ยงสูงต่อการผิดพลาด

Independent Test: รัน npm run test:cov แล้วดู Statements Coverage ≥ 50%

Acceptance Scenarios:

1. Given components/rfas/ มี 0% coverage, When เขียน test ครอบ form validation, status transition, และ list rendering, Then folder นั้นมี coverage ≥ 60%
2. Given lib/api/ มี coverage เกือบ 0%, When เขียน test ด้วย mock HTTP client สำหรับ CRUD operations, Then API functions มี coverage ≥ 70%
3. Given components/auth/ มี 0% coverage, When เขียน test ครอบ login form validation, Then coverage ≥ 70%

---

User Story 3 — Phase 3: ยก Coverage จาก 50% → 70% (Priority: P3)

ทีมพัฒนาสามารถรันคำสั่งทดสอบและเห็นตัวเลข Statement Coverage รวมที่ไม่ต่ำกว่า 70% โดยระยะนี้เพิ่มการทดสอบในส่วน:

• components/admin/ ทั้งหมด (รวม admin/ai, admin/reference, admin/security)
• components/workflow/ และ components/workflows/
• components/layout/
• components/transmittal/, components/circulation/
• lib/stores/, lib/utils/, lib/i18n/

Why this priority: ส่วน Admin และ Workflow เป็นระบบที่ซับซ้อนและมี edge case สูง แต่ใช้งานโดยผู้ดูแลระบบเท่านั้น จึงวางไว้ในระยะสุดท้าย

Independent Test: รัน npm run test:cov แล้วดู Statements Coverage ≥ 70%

Acceptance Scenarios:

1. Given components/admin/ มี 0% coverage, When เขียน test ครอบ AI admin panel, reference management, security settings, Then folder นั้นมี coverage ≥ 60%
2. Given components/workflow/ มี 0% coverage, When เขียน test ครอบ workflow state display และ transition triggers, Then folder นั้นมี coverage ≥ 65%
3. Given ระบบทั้งหมด, When รัน test suite หลังเขียนครบ Phase 3, Then Statement Coverage รวม ≥ 70%

---

Edge Cases

• Component ที่มี async data fetching ต้องทดสอบทั้ง loading state, success state, และ error state
• Form validation ต้องทดสอบ edge case ของ input (ว่าง, ยาวเกิน, HTML injection)
• Component ที่ใช้ publicId ต้องทดสอบว่าไม่ส่ง id หรือ uuid ไปแทน (ADR-019)
• i18n keys ต้องทดสอบว่า render ค่าจาก translation file ไม่ใช่ hardcoded text

---

Requirements (mandatory)

Functional Requirements

• FR-001: ทุก Custom Hook ใน hooks/ MUST มี test ครอบ happy path และ error path อย่างน้อย
• FR-002: ทุก Service function ใน lib/services/ MUST มี test ด้วย mock HTTP client
• FR-003: Component ที่ render form MUST มี test ครอบ validation และ submission
• FR-004: Component ที่มี conditional rendering (เช่น สถานะเอกสาร) MUST มี test ครอบทุก branch
• FR-005: ต้องไม่เขียน test ที่ใช้ parseInt กับ publicId หรือมี id ?? '' fallback (ADR-019)
• FR-006: Test ทุกตัวต้อง mock HTTP calls ด้วย vi.mock หรือ MSW — ห้ามเรียก API จริง
• FR-007: Test files ต้องตั้งชื่อเป็น *.spec.tsx หรือ *.spec.ts และวางข้างๆ source file
• FR-008: แต่ละ Phase ต้อง manual verify โดยรัน npm run test:cov และยืนยันว่า Statement Coverage ถึงเป้าก่อน merge เข้า main branch — ไม่ต้องตั้ง CI threshold อัตโนมัติ
• FR-009: Coverage report ต้อง generate ใหม่หลังแต่ละ Phase เสร็จเพื่อยืนยันตัวเลข
• FR-010: ต้องใช้ Thai สำหรับ comment และ JSDoc ใน test files ตามมาตรฐานโปรเจกต์
• FR-011: หากการเขียน test พบว่า component มี bug จริง ต้อง fix bug ในทันที และ commit พร้อมกับ test ใน PR เดียวกัน — ห้าม skip หรือเขียน test ที่ยอมให้ fail ผ่านไป

Clarifications

Session 2026-06-13

• Q: Phase Gate ควร enforce ที่ระดับไหน? → A: Manual check — รัน npm run test:cov ดูตัวเลขก่อน merge แต่ละ Phase ไม่ต้องตั้ง CI threshold อัตโนมัติ
• Q: หากพบ bug ระหว่างเขียน test ควรทำอย่างไร? → A: Fix bug ทันที — แก้ bug แล้ว commit พร้อมกับ test ใน PR เดียวกัน ห้าม skip หรือปล่อยผ่าน

Key Entities

• Coverage Report: HTML report ที่ generate โดย Istanbul.js จากการรัน npm run test:cov
• Test Suite: ชุดไฟล์ *.spec.tsx / *.spec.ts ที่เพิ่มขึ้นในแต่ละ Phase
• Phase Gate: เกณฑ์ Coverage % ที่ต้องผ่านก่อนจะ merge Phase นั้นและเริ่ม Phase ถัดไป

---

Success Criteria (mandatory)

Measurable Outcomes

• SC-001 (Phase 1): Statement Coverage ของ Frontend ≥ 30% หลังจากเขียน test สำหรับ hooks/ และ lib/services/
• SC-002 (Phase 2): Statement Coverage ≥ 50% หลังจากเพิ่ม test สำหรับ rfas/, numbering/, drawings/, lib/api/
• SC-003 (Phase 3): Statement Coverage ≥ 70% หลังจากเพิ่ม test สำหรับ admin/, workflow/, layout/
• SC-004: Branch Coverage ตามไปอย่างน้อย 50% ของ Statement Coverage ในแต่ละ Phase
• SC-005: Test suite ทั้งหมดต้องผ่าน (0 failed) ก่อน merge แต่ละ Phase
• SC-006: ไม่มี test ที่ใช้ any type หรือ console.log ในโค้ด test

Assumptions

• ใช้ Vitest + React Testing Library เป็น test framework หลัก (ตาม 05-04-testing-strategy.md)
• Mock HTTP calls ด้วย vi.mock หรือ Mock Service Worker (MSW)
• ไม่ต้องเพิ่ม dependencies ใหม่หากสามารถใช้ tools ที่มีอยู่ได้
• การจัดลำดับ Phase ขึ้นอยู่กับขนาด (statements count) และความสำคัญทางธุรกิจ
• E2E Tests (Playwright) ไม่นับรวมใน Coverage report นี้ — เป็นแยกต่างหาก