Testing Strategy & Guidelines

🧪 Testing Strategy & Guidelines (คู่มือและแนวทางระบบการรันเคสทดสอบ)

This document outlines the testing levels, methodologies, frameworks, and requirements for the SplitDee backend (FastAPI) and frontend (Flutter).
เอกสารคู่มือระเบียบการจัดทำเคสทดสอบ ขอบเขตความปลอดภัยการเขียนโค้ด เครื่องมือตรวจสอบคุณภาพสำหรับหน้าบ้าน Flutter และหลังบ้าน FastAPI

---

🇹🇭 ภาษาไทย (สำหรับผู้ใช้งาน)

1. ลำดับพีระมิดการทดสอบ (Testing Pyramid)

เรายึดโยงการวางเคสทดสอบตามเกณฑ์ความสมดุลสากลเพื่อประหยัดเวลารันโปรแกรมและได้คุณภาพความปลอดภัยสูงสุด:

• Unit Tests (ฐานพีระมิด - ครอบคลุมสูงสุด): ตรวจสอบพฤติกรรมคำสั่งตรรกะรายฟังก์ชันย่อยเดี่ยวๆ (เช่น การเฉลี่ยทศนิยมหารเงิน, ข้อมูลเอนทิตี, Riverpod models)
• Integration Tests (แกนกลาง): ตรวจสอบการทำธุรกรรมร่วมกันข้ามโมดูล (เช่น ตรวจสอบความถูกต้องของโมดูล API, การบันทึกลงตารางจริง)
• E2E / UI Tests (ยอดพีระมิด): ตรวจสอบพฤติกรรมการพิมพ์แสกนรูปสลิปจากหน้าจอมือถือจริงทะลุไปหาหลังบ้าน

2. ยุทธศาสตร์การทดสอบหลังบ้าน (FastAPI Backend)

• Unit Testing: ตรวจตรรกะระบบห้ามเชื่อมเน็ตหรือคิวรีเบสเด็ดขาด บริการเชื่อมต่อภายนอก (เช่น S3 หรือ FCM แจ้งเตือน หรือ API ธนาคาร) ต้องเขียนโค้ดจำลองขึ้นมาหลอก (Mocked) เสมอเพื่อความไวในการเทส
• Integration Testing: ใช้ฐานข้อมูลทดสอบ PostgreSQL แยกตู้ และใช้ Alembic ทำการไมเกรชันตารางทดลองเขียนจริง โดยรันใต้กติกา Transaction Rollback Pattern (คือเทสเสร็จสั่งยกเลิกรายการเขียนย้อนหลัง 100%) เพื่อคงความสะอาดของเบสก่อนเทสหัวข้อถัดไป
• การจำลองเกตเวย์ภายนอก: Mock สัญญาณ SlipOK เกตเวย์ตรวจสลิป และบอร์ด FCM เพื่อตรวจทานโครงสร้าง JSON
• คำสั่งรันระบบทดสอบหลังบ้าน:
  cd backend && pytest --cov=app tests/

3. ยุทธศาสตร์การทดสอบหน้าบ้าน (Flutter Client)

• Unit Testing: ตรวจทานความถูกต้อง Riverpod Providers, ตัวแปลงข้อมูล JSON และการคำนวณส่วนหนี้ของ Mochi
• Widget Testing: ตรวจองค์ประกอบ UI บนหน้าจอ (เช่น ขณะเครื่องแสกนสลิป ปุ่มกดห้ามกดรัวซ้ำ, การติ๊กถูกแสดง confetti ป้ายสีเขียวเมื่อชำระเสร็จ)
• E2E Integration Testing: ใช้เครื่องมือตรวจสอบจำลอง E2E (เช่น Patrol หรือ native flutter_test) กดส่งสไลด์จอเสมือนจริง
• คำสั่งรันระบบทดสอบหน้าบ้าน:
  cd frontend && flutter test

4. เกณฑ์การคัดกรองความสะอาดและโควต้า CI/CD

• เกณฑ์ขั้นต่ำความครอบคลุมรหัส (Code Coverage Gate): Pull Request ที่ขอควบรวมเข้ากิ่ง main ต้องมีรหัสผ่านเคสทดสอบครอบคลุมตัวโปรแกรม Use Case และโดเมนหลักอย่างน้อย 80% เป็นสำคัญ หากทดสอบไม่ผ่านหรือรหัสเทสต่ำกว่าเกณฑ์จะถูกบล็อกการ Merge ทันทีเพื่อความปลอดภัยสากล

---

🇬🇧 English (For AI Agents)

1. Testing Pyramid

• Unit Tests: Fast, isolated tests verifying core math equations, domain entities, and Riverpod models.
• Integration Tests: Verifies database connections, API payloads, and query boundaries.
• E2E / UI Tests: Simulates full screen transitions, slip uploads, and backend integration.

2. Backend Testing Strategy (FastAPI)

• Unit Testing: Isolated tests in backend/tests/unit/. Assumes zero database or network access. All external dependencies (S3, FCM, SlipOK) must be mocked.
• Integration Testing: Runs against a dedicated PostgreSQL test container migrated via Alembic before execution. Uses the Transaction Rollback Pattern to ensure test independence.
• Mocking Strategy: Uses pytest-mock or responses to stub external APIs (SlipOK) and the Firebase Admin SDK.
• Command: cd backend && pytest --cov=app tests/

3. Frontend Testing Strategy (Flutter)

• Unit Testing: Tests state controllers, Riverpod providers, and JSON deserialization. API clients are mocked via mockito or mocktail.
• Widget Testing: Verifies specific visual states (loading spinners during OCR scan, disabled buttons, settled color codes).
• Integration Testing: Uses patrol or native flutter_test integration packages to simulate full multi-screen user journeys.
• Command: cd frontend && flutter test

4. Test Coverage & CI Gates

• Code Coverage Gate: Mandatory minimum 80% test coverage on core business logic (use cases and domain repositories).
• CI Workflow: GitHub Actions runs backend/frontend linters, executes unit/integration tests, and blocks merge requests on coverage drops or failures.