@anhlp/alp-core 0.0.1-beta.7 → 0.0.1-beta.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/dist/library-edit.d.ts +51 -2
  2. package/dist/library-edit.js +160 -8
  3. package/dist/library.d.ts +14 -1
  4. package/dist/library.js +73 -5
  5. package/dist/models.d.ts +35 -0
  6. package/dist/models.js +17 -1
  7. package/dist/packs.d.ts +57 -0
  8. package/dist/packs.js +247 -0
  9. package/dist/permissions.d.ts +3 -2
  10. package/dist/permissions.js +6 -3
  11. package/dist/profiles.js +3 -3
  12. package/dist/providers.d.ts +2 -4
  13. package/dist/providers.js +20 -4
  14. package/dist/skill-validate.d.ts +85 -0
  15. package/dist/skill-validate.js +298 -0
  16. package/dist/upgrade.d.ts +10 -0
  17. package/dist/upgrade.js +112 -6
  18. package/dist/validation.js +2 -3
  19. package/package.json +18 -2
  20. package/src/library-edit.js +170 -8
  21. package/src/library.js +96 -6
  22. package/src/models.js +24 -0
  23. package/src/packs.js +246 -0
  24. package/src/permissions.d.ts +3 -2
  25. package/src/permissions.js +13 -3
  26. package/src/profiles.js +4 -4
  27. package/src/providers.js +20 -5
  28. package/src/resolver.js +1 -1
  29. package/src/skill-validate.js +287 -0
  30. package/src/upgrade.js +54 -6
  31. package/src/validation.js +3 -4
  32. package/templates/ALP.md +52 -52
  33. package/templates/agents/lead/AGENT.md +77 -74
  34. package/templates/agents/main/AGENT.md +153 -145
  35. package/templates/agents/oracle/AGENT.md +38 -37
  36. package/templates/agents/peer/AGENT.md +56 -52
  37. package/templates/agents/reviewer/AGENT.md +63 -65
  38. package/templates/agents/supervisor/AGENT.md +63 -63
  39. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  40. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  41. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  42. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  43. package/templates/packs/architecture/pack.json +7 -0
  44. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  45. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  46. package/templates/packs/backend/pack.json +6 -0
  47. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  48. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  49. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  50. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  51. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  52. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  53. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  54. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  55. package/templates/packs/design/pack.json +6 -0
  56. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  57. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  58. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  59. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  60. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  61. package/templates/packs/frontend/pack.json +6 -0
  62. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  63. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  64. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  65. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  66. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  67. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  68. package/templates/packs/integration/pack.json +6 -0
  69. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  70. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  71. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  72. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  73. package/templates/packs/operations/pack.json +6 -0
  74. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  75. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  76. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  77. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  78. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  79. package/templates/packs/quality/pack.json +6 -0
  80. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  81. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  82. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  83. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  84. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  85. package/templates/role-skills.json +4 -4
  86. package/templates/skills/architecture-docs/SKILL.md +81 -0
  87. package/templates/skills/architecture-docs/references/adr.md +62 -0
  88. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  89. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  90. package/templates/skills/bug-loop/SKILL.md +41 -40
  91. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  92. package/templates/skills/compact/SKILL.md +2 -2
  93. package/templates/skills/curate/SKILL.md +6 -5
  94. package/templates/skills/feature-architecture/SKILL.md +90 -0
  95. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  96. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  97. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  98. package/templates/skills/goal-griller/SKILL.md +27 -27
  99. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  100. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  101. package/templates/skills/release-readiness/SKILL.md +83 -0
  102. package/templates/skills/release-readiness/references/checklist.md +40 -0
  103. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  104. package/templates/skills/safe-refactor/SKILL.md +84 -0
  105. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  106. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  107. package/templates/skills/security-review/SKILL.md +87 -0
  108. package/templates/skills/security-review/references/checklist.md +74 -0
  109. package/templates/skills/security-review/references/severity.md +61 -0
  110. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  111. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  112. package/templates/skills/skill-authoring/SKILL.md +84 -0
  113. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  114. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  115. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  116. package/templates/skills/smart-commits/SKILL.md +37 -36
  117. package/templates/skills/test-strategy/SKILL.md +83 -0
  118. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  119. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  120. package/templates/skills/xia/SKILL.md +40 -38
  121. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  122. package/templates/teams/cafe/team.json +1 -1
  123. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  124. package/templates/teams/pho/team.json +1 -1
@@ -0,0 +1,85 @@
1
+ # Deploy và rollback
2
+
3
+ Đọc khi lên kế hoạch rollout, sắp thứ tự migration database, hoặc viết và diễn tập một lần rollback.
4
+
5
+ Đầu ra mặc định là bản kế hoạch. Thực thi bất kỳ bước nào lên môi trường dùng chung hay production
6
+ đều cần phép tường minh cho đúng bước đó.
7
+
8
+ ## Chọn một chiến lược
9
+
10
+ | Chiến lược | Cách làm | Phù hợp với | Cái giá |
11
+ |---|---|---|---|
12
+ | Rolling | Thay instance theo từng lô | Service không giữ state, các phiên bản tương thích nhau | Lẫn nhiều phiên bản trong lúc rollout |
13
+ | Blue/green | Chạy stack mới song song stack cũ, chuyển lưu lượng một lần | Rollback nhanh và gọn; đổi config hay runtime | Cần gấp đôi năng lực trong lúc chuyển |
14
+ | Canary | Đẩy một phần nhỏ lưu lượng sang bản mới, rồi mở rộng dần | Thay đổi rủi ro, lưu lượng lớn, có chỉ số tốt | Cần chia lưu lượng và cần so sánh |
15
+ | Feature flag | Đưa code lên nhưng tắt, rồi bật theo từng nhóm | Thay đổi hành vi độc lập với việc deploy | Nợ flag; cần dọn về sau |
16
+ | Recreate | Tắt bản cũ, bật bản mới | Môi trường dev hay job theo lô, nơi downtime không sao | Có downtime |
17
+
18
+ Hãy dùng chiến lược mà nền tảng và dự án đã hỗ trợ. Đưa vào việc chia lưu lượng, một
19
+ dịch vụ flag hay thêm môi trường là quyết định của chủ sở hữu.
20
+
21
+ ## Nội dung của một kế hoạch rollout
22
+
23
+ - Định danh phiên bản hay artifact đang được deploy, và cái đang bị thay thế.
24
+ - Tiền điều kiện: test đã pass, đã xác nhận migration tương thích, người trực đã biết nếu dự án
25
+ yêu cầu, và khung thời gian thay đổi nếu có.
26
+ - Các bước kèm đúng lệnh hay đúng hành động pipeline, theo thứ tự.
27
+ - Tín hiệu thành công: những chỉ số, log hay kiểm tra nào, kèm ngưỡng và thời gian theo dõi cho mỗi bước.
28
+ - Tiêu chí hủy: cái gì làm khởi động rollback (tỉ lệ lỗi, độ trễ, độ bão hòa, healthcheck fail).
29
+ - Các bước rollback (bên dưới) và ai được phép thực hiện chúng.
30
+
31
+ ## Canary và giao hàng tăng dần
32
+
33
+ - Các bước như 1% rồi 5%, 25%, 50%, 100%, kèm một khoảng theo dõi ở mỗi mức. Hãy dùng cái nền tảng hỗ trợ.
34
+ - So canary với mốc cơ sở trên cùng các chỉ số trong cùng một khoảng thời gian, không so với
35
+ hôm qua.
36
+ - Tự động hủy khi vượt ngưỡng rõ rệt, ở nơi có công cụ; nếu không, hãy chỉ định một người theo dõi.
37
+ - Bảo đảm canary nhận được lưu lượng mang tính đại diện (các vùng, các loại client).
38
+
39
+ ## Blue/green
40
+
41
+ - Làm nóng stack mới và chạy các kiểm tra smoke trước khi chuyển.
42
+ - Giữ stack cũ vẫn chạy và không chạm tới nó cho tới khi hết khoảng theo dõi.
43
+ - Chuyển đi và chuyển lại bằng cùng một cơ chế (load balancer, DNS với TTL thấp, router).
44
+ - Để ý các kết nối sống lâu, session và cache khi chuyển qua.
45
+
46
+ ## Thứ tự migration database (mở rộng rồi thu hẹp)
47
+
48
+ Code và schema phải tương thích nhau suốt cả lần rollout và cả lần rollback.
49
+
50
+ 1. **Mở rộng:** thêm cột, bảng hay index mới theo cách tương thích ngược (cho phép null hoặc có
51
+ giá trị mặc định; tạo index mà không khóa lâu, ở nơi database hỗ trợ).
52
+ 2. **Deploy code** ghi cả hình dạng cũ và mới, hoặc đọc hình dạng mới và quay về cũ khi cần.
53
+ 3. **Backfill** theo từng lô nhỏ có điều tiết; làm nó tiếp tục được và idempotent.
54
+ 4. **Chuyển phần đọc** sang hình dạng mới; rồi kiểm chứng.
55
+ 5. **Thu hẹp:** bỏ cột cũ hay các đường code cũ ở một bản release sau, sau khi hết khung rollback.
56
+
57
+ - Không bao giờ gộp một migration phá hủy với chính thay đổi code phụ thuộc vào nó.
58
+ - Hãy ước lượng tác động khóa và thời lượng trên dữ liệu cỡ production trước khi chạy.
59
+ - Backup hay snapshot trước những bước không đảo lại được, và xác nhận là quy trình phục hồi chạy được.
60
+ - Migration chạy một lần, từ một chỗ duy nhất (job pipeline hay bước release), không chạy từ mỗi instance.
61
+
62
+ ## Rollback
63
+
64
+ - Ứng dụng: deploy lại artifact bất biến trước đó qua pipeline bình thường, hoặc chuyển
65
+ lưu lượng về (blue/green), hoặc giảm canary về 0%.
66
+ - Cấu hình và flag: hoàn tác đúng thay đổi đó; giữ config có phiên bản.
67
+ - Schema: với mở rộng/thu hẹp, code cũ vẫn chạy được, nên chỉ cần rollback code. Một lần rollback cần tới
68
+ một migration đi xuống là rất rủi ro; hãy ưu tiên sửa tiến lên, trừ khi đường đi xuống đã được test.
69
+ - Hạ tầng: hoàn tác thay đổi IaC rồi chạy plan; kiểm xem có tài nguyên nào không tạo lại được
70
+ (kho dữ liệu, IP tĩnh) trước khi destroy bất cứ gì.
71
+ - Dữ liệu do bản mới ghi ra phải vẫn đọc được bởi bản cũ, hoặc kế hoạch rollback
72
+ phải nói rõ nó được xử lý thế nào.
73
+
74
+ ## Diễn tập
75
+
76
+ - Hãy diễn tập rollback trong một môi trường không phải production với những thay đổi mới, rủi ro hoặc chạm tới
77
+ schema. Ghi lại lệnh, thời lượng và kết quả.
78
+ - Nếu không diễn tập được, hãy ghi vào kế hoạch là "rollback chưa diễn tập" và nêu rủi ro.
79
+ - Bấm thời gian từng bước; một lần rollback chậm hơn mức downtime chịu được thì cần một chiến lược khác.
80
+
81
+ ## Sau khi deploy
82
+
83
+ - Theo dõi các tín hiệu thành công trong khoảng thời gian đã nêu; xác nhận ngân sách lỗi và các alert đều im.
84
+ - Ghi lại cái gì đã được deploy, khi nào, bởi ai, và mọi chỗ lệch khỏi kế hoạch.
85
+ - Lên lịch cho bước thu hẹp và việc dọn flag.
@@ -0,0 +1,86 @@
1
+ # Observability
2
+
3
+ Đọc khi thêm hay review log, metric, trace, SLO, alert hay dashboard.
4
+
5
+ Hãy dùng stack telemetry mà dự án đã có. Thêm một agent, nhà cung cấp, collector hay gói
6
+ trả phí là quyết định của chủ sở hữu.
7
+
8
+ ## Log
9
+
10
+ - Có cấu trúc (JSON hoặc định dạng của dự án) với các field nhất quán: timestamp, level, service,
11
+ môi trường, phiên bản, ID của request hay của trace, tên event, kết quả, thời lượng.
12
+ - Các level phải có ý nghĩa: error = cần ai đó để ý, warn = suy giảm nhưng đã xử lý được, info = những
13
+ event nghiệp vụ hay vòng đời đáng kể, debug = mặc định tắt ở production.
14
+ - Hãy ghi log dạng event, không kể chuyện: `event=payment_failed reason=card_declined order_id=...`.
15
+ - Không bao giờ ghi log secret, token, mật khẩu, số thẻ đầy đủ hay dữ liệu cá nhân không cần thiết. Hãy che
16
+ ngay tại logger, không chỉ dựa vào quy ước.
17
+ - Ghi ra stdout/stderr trong container; để nền tảng thu thập và chuyển đi.
18
+ - Kiểm soát lượng log: lấy mẫu các log thành công ồn ào, không lấy mẫu các log lỗi. Tránh ghi log trong vòng lặp chặt.
19
+
20
+ ## Metric
21
+
22
+ - Request (RED): tần suất, lỗi, thời lượng cho mọi endpoint service hay consumer hàng đợi.
23
+ - Tài nguyên (USE): mức sử dụng, độ bão hòa, lỗi cho CPU, bộ nhớ, đĩa, pool kết nối, hàng đợi.
24
+ - Những tín hiệu nghiệp vụ cho thấy tác động tới người dùng: số lần đăng ký xong, số đơn đã đặt, số job đã xử lý.
25
+ - Thời lượng thì dùng histogram, không dùng giá trị trung bình; hãy báo p50, p95, p99.
26
+ - Giữ lực lượng của label có giới hạn: không dùng ID người dùng, ID request hay URL thô làm label; hãy dùng mẫu route.
27
+ - Đặt tên metric kèm đơn vị và theo quy ước đặt tên của dự án.
28
+
29
+ ## Trace
30
+
31
+ - Truyền ngữ cảnh qua các biên service bằng những header chuẩn mà stack dùng
32
+ (W3C trace context là phổ biến); kèm ID của trace vào log để liên kết chúng lại.
33
+ - Tạo span cho những đơn vị đáng quan tâm: request vào, các lệnh gọi ra, truy vấn database, publish và
34
+ consume hàng đợi. Tránh tạo một span cho mỗi hàm.
35
+ - Ghi những thuộc tính giúp chẩn đoán (route, status, số lần retry), không ghi payload.
36
+ - Lấy mẫu ở mức mà backend chịu được; hãy giữ lại các trace lỗi và trace chậm khi công cụ hỗ trợ.
37
+
38
+ ## SLO
39
+
40
+ - Hãy bắt đầu từ hành vi người dùng thấy được: độ khả dụng (request thành công / request hợp lệ) và
41
+ độ trễ (tỉ lệ request dưới một ngưỡng), cho từng hành trình người dùng quan trọng.
42
+ - Định nghĩa rõ: công thức SLI, mục tiêu (ví dụ 99.5% trong 28 ngày), khung thời gian, và cái gì được tính là hợp lệ.
43
+ - Ngân sách lỗi là 100% trừ đi mục tiêu. Mức tiêu ngân sách định hướng nhịp phát hành và việc làm độ tin cậy;
44
+ còn đội phản ứng với nó thế nào là chính sách của chủ sở hữu.
45
+ - Chọn mục tiêu từ hiệu năng đang đo được và từ nhu cầu người dùng, không chọn những con số tròn trịa mang tính khát vọng.
46
+ - Mỗi service chỉ vài SLO; mỗi cái đều có một người sở hữu.
47
+
48
+ ## Alert hành động được
49
+
50
+ - Mỗi lần gọi người phải trả lời được: cái gì đang vỡ với người dùng, nặng tới đâu, và phải làm gì trước.
51
+ - Gọi người theo triệu chứng (mức tiêu SLO, tỉ lệ lỗi, độ trễ, độ bão hòa gần cạn), không gọi theo mọi
52
+ nguyên nhân (CPU một host vọt lên, một lần retry thất bại).
53
+ - Ưu tiên alert theo tốc độ tiêu ngân sách trên nhiều khung thời gian cho SLO: khung nhanh bắt các sự cố gắt, khung chậm
54
+ bắt sự suy giảm đều đều.
55
+ - Mỗi alert đều có: tên rõ ràng, mức nghiêm trọng, ngưỡng và thời lượng, người sở hữu, link runbook hay bước
56
+ chẩn đoán đầu tiên, và một link dashboard.
57
+ - Những điều kiện không gấp thì thành ticket hay báo cáo, không thành cuộc gọi người.
58
+ - Hãy test alert: kích hoạt nó trong môi trường không phải production hoặc bằng một điều kiện tổng hợp và xác nhận
59
+ là nó được gửi tới và runbook là đúng.
60
+ - Hãy xem lại những alert đã nổ mà không ai làm gì hoặc bị tắt tiếng; hãy chỉnh lại hoặc xóa chúng.
61
+
62
+ ## Dashboard
63
+
64
+ - Một trang tổng quan cho mỗi service: trạng thái SLO, các chỉ số RED, độ bão hòa, có đánh dấu các lần deploy gần đây.
65
+ - Dashboard đi sâu cho từng phụ thuộc. Cùng khoảng thời gian và cùng đơn vị trên khắp các panel.
66
+ - Ưu tiên ít panel nhưng ghi nhãn tốt, hơn là nhiều panel không ai giải thích.
67
+
68
+ ## Runbook
69
+
70
+ - Ngắn: triệu chứng, tác động, các bước kiểm đầu tiên (dashboard, truy vấn log), các cách giảm thiểu an toàn (rollback,
71
+ scale, tắt flag), đường chuyển lên.
72
+ - Những cách giảm thiểu có làm đổi production thì vẫn cần đúng sự cho phép mà runbook nêu ra.
73
+
74
+ ## Thêm telemetry cho một thay đổi
75
+
76
+ - Xác định những chế độ lỗi mới mà thay đổi đó đưa vào và làm cho từng cái thấy được: một event log,
77
+ một metric lỗi, hoặc một thuộc tính span.
78
+ - Thêm tín hiệu đó trước hoặc cùng lúc với thay đổi, để có thể theo dõi được lần rollout.
79
+ - Nêu trong handoff những tín hiệu nào cho thấy thành công và những tín hiệu nào cho thấy thất bại.
80
+
81
+ ## Checklist review
82
+
83
+ - Không có secret hay dữ liệu cá nhân quá mức trong log, label hay span.
84
+ - Lực lượng label có giới hạn; độ trễ dùng histogram.
85
+ - Alert dựa trên triệu chứng, có người sở hữu, có runbook; không có alert nào mà không kèm hành động.
86
+ - SLO được định nghĩa từ các hành trình người dùng với mốc cơ sở đã đo.
@@ -0,0 +1,6 @@
1
+ {
2
+ "label": "Quality",
3
+ "description": "Kiểm thử web ở mức tooling: end-to-end, unit và component, kiểm thử hiệu năng và bảo mật trong môi trường test.",
4
+ "skills": ["web-testing"],
5
+ "assign": { "lead": ["web-testing"], "peer": ["web-testing"], "reviewer": ["web-testing"] }
6
+ }
@@ -0,0 +1,102 @@
1
+ ---
2
+ name: web-testing
3
+ description: "Viết và chạy test web bằng công cụ của dự án: e2e (kiểu Playwright), unit và component (kiểu Vitest hay Jest), kiểm thị giác và accessibility, test hiệu năng và tải (kiểu k6), và các kiểm tra bảo mật cơ bản, chỉ trên môi trường test. Dùng khi thêm, sửa, hay chạy các bộ test web. Không dùng cho thiết kế test (test-strategy) hay chẩn đoán lỗi (bug-loop)."
4
+ ---
5
+
6
+ # Test web
7
+
8
+ ## Khi nào dùng
9
+
10
+ - Thêm hoặc cập nhật test e2e, unit, component, thị giác, hay accessibility cho một app
11
+ web.
12
+ - Làm cho một bộ test web chập chờn hay chậm trở nên tin cậy ở tầng công cụ (selector, chờ,
13
+ cách ly, fixture, trace).
14
+ - Chạy một mốc hiệu năng cơ sở hoặc test tải trên một môi trường test.
15
+ - Chạy các kiểm tra bảo mật cơ bản đã được phép (audit phụ thuộc, kiểm header, test luồng
16
+ auth) trên một môi trường test.
17
+ - Một reviewer chỉ đọc được nhờ đánh giá code test (chỉ tư vấn).
18
+
19
+ ## Không dùng cho
20
+
21
+ - Quyết định test cái gì, ở tầng nào, và vì sao: dùng test-strategy.
22
+ - Một test fail hay hồi quy mà chưa rõ nguyên nhân: dùng bug-loop.
23
+ - Audit bảo mật hay review mối đe dọa của code: dùng security-review.
24
+ - Dựng chính tính năng đang được test: dùng frontend-development hay backend-development.
25
+ - Chọn framework test, runner, hay dịch vụ mới: quyết định của chủ sở hữu.
26
+
27
+ ## Điều kiện tiên quyết
28
+
29
+ - Đường dẫn sở hữu và tiêu chí nghiệm thu trong brief; ALP.md và chỉ dẫn của dự án.
30
+ - Công cụ test và các lệnh đang có, đọc từ phần scripts của `package.json` (hoặc
31
+ tương đương), file config của runner, và config CI. Không suy ra từ tên thư mục.
32
+ - Các test đang có gần chỗ thay đổi. Chúng định ra cách đặt tên, fixture, helper, và cách
33
+ app được khởi động để test.
34
+ - Một môi trường test: dev server cục bộ, bản build preview, hoặc một bản
35
+ deploy test riêng. Không bao giờ là production trừ khi chủ sở hữu cho phép tường minh.
36
+ - Tài khoản và dữ liệu test lấy từ fixture hay script seed của dự án; không bao giờ dùng thông tin
37
+ đăng nhập của người dùng thật.
38
+
39
+ ## Quy trình
40
+
41
+ 1. Lấy các ca cần bao phủ từ brief hoặc từ đầu ra của test-strategy. Nếu chưa có,
42
+ hãy liệt kê các hành vi người dùng thấy được và chuyển việc chọn lên trên khi nó quan trọng.
43
+ 2. Chọn tầng rẻ nhất chứng minh được từng ca: unit cho logic, component cho
44
+ render và tương tác, e2e cho một ít luồng liên trang then chốt. Đọc
45
+ unit-and-component.md hoặc e2e.md.
46
+ 3. Dùng lại fixture, page object, factory, và helper đang có trước khi viết cái
47
+ mới.
48
+ 4. Viết mỗi test sao cho nó độc lập: dữ liệu riêng, không phụ thuộc thứ tự, không dùng chung
49
+ state thay đổi được, dọn dẹp hoặc có state mới cho mỗi test.
50
+ 5. Truy vấn phần tử theo vai trò, nhãn, hay chữ thấy được; chờ theo điều kiện, không bao giờ
51
+ chờ theo thời gian ngủ cố định.
52
+ 6. Chỉ thêm kiểm thị giác hay accessibility ở nơi dự án đã chạy chúng hoặc
53
+ brief yêu cầu; giữ snapshot nhỏ và tất định.
54
+ 7. Với việc hiệu năng hay tải, hãy đọc performance-testing.md; lập mốc cơ sở
55
+ trước khi so sánh, và xin phép tường minh cho bất kỳ đích dùng chung nào.
56
+ 8. Với kiểm tra bảo mật, hãy đọc security-testing.md; chỉ chạy những kiểm tra an toàn trên
57
+ môi trường bạn được phép test.
58
+ 9. Chạy các test mới và bộ test xung quanh bằng lệnh của dự án. Chạy một
59
+ test e2e mới vài lần ở máy cục bộ để lộ ra sự chập chờn.
60
+ 10. Handoff: test đã thêm hay đổi, lệnh kèm kết quả, các lần chạy kiểm chập chờn, chỗ chứa
61
+ artifact (trace, báo cáo), các khoảng trống, và những gì cần chủ sở hữu quyết định.
62
+
63
+ ## Ràng buộc
64
+
65
+ - Trước hết hãy theo stack test và quy ước đang có của dự án. Playwright,
66
+ Cypress, Vitest, Jest, Testing Library, axe, k6, hay Lighthouse chỉ là ví dụ, không phải
67
+ khuyến nghị.
68
+ - Không thêm framework test, browser, plugin, hay dịch vụ mà không có quyết định của
69
+ chủ sở hữu. Không tự động cài; nếu thiếu một binary browser hay một công cụ, hãy báo lại.
70
+ - Không bao giờ test tải, quét, hay thăm dò production hay hệ thống của bên thứ ba mà không có
71
+ văn bản cho phép tường minh của chủ sở hữu.
72
+ - Không bao giờ dùng thông tin đăng nhập thật hay dữ liệu cá nhân; dùng tài khoản test và dữ liệu tổng hợp.
73
+ - Không làm yếu các assertion, không thêm retry, không skip test để bộ test pass; một test
74
+ chập chờn hay fail thì chuyển sang bug-loop.
75
+ - Không cập nhật snapshot hay mốc cơ sở mà chưa kiểm rằng output mới đúng là
76
+ hành vi mong muốn.
77
+ - Ở trong đường dẫn sở hữu. Sửa cấu hình CI là ngoài phạm vi trừ khi được giao.
78
+
79
+ ## Kiểm chứng
80
+
81
+ - Test mới phải fail khi không có hành vi nó bao phủ (hoặc khi hành vi đó bị vỡ) và pass
82
+ khi có.
83
+ - Test e2e mới pass qua nhiều lần chạy lặp lại (ví dụ ba tới năm lần) mà không cần retry.
84
+ - Bộ test xung quanh vẫn pass với lệnh của dự án.
85
+ - Không có thời gian ngủ cố định, không phụ thuộc thứ tự, không có secret thật trong test mới.
86
+ - Kết quả hiệu năng kèm mốc cơ sở, điều kiện đo, và môi trường đích.
87
+
88
+ ## Xử lý khi thất bại
89
+
90
+ - Thiếu công cụ hay browser, hoặc app không khởi động được ở đây: báo đúng lệnh
91
+ và lỗi đó; không khẳng định là test đã chạy.
92
+ - Một test chập chờn: ghi lại trace hay log, rồi chuyển sang bug-loop để tìm nguyên nhân.
93
+ - Một test lộ ra bug của sản phẩm: báo nó kèm cách tái hiện; không sửa
94
+ test cho khớp với hành vi sai.
95
+ - Chưa rõ việc cho phép với một đích tải hay bảo mật: dừng lại và chuyển lên trên.
96
+
97
+ ## Tài liệu tham chiếu
98
+
99
+ - [references/e2e.md](references/e2e.md) — đọc khi viết hay làm ổn định test end-to-end trên browser (bước 2-5).
100
+ - [references/unit-and-component.md](references/unit-and-component.md) — đọc khi viết test unit hay component, mock, hay snapshot (bước 2-6).
101
+ - [references/performance-testing.md](references/performance-testing.md) — đọc khi chạy mốc hiệu năng cơ sở, ngân sách, hay test tải (bước 7).
102
+ - [references/security-testing.md](references/security-testing.md) — đọc khi chạy audit phụ thuộc, kiểm header, hay test luồng auth (bước 8).
@@ -0,0 +1,85 @@
1
+ # Test end-to-end
2
+
3
+ Đọc khi viết hay làm ổn định test end-to-end trên browser.
4
+
5
+ Ví dụ dùng API kiểu Playwright; Cypress và các công cụ dựa trên WebDriver đều có
6
+ cái tương đương. Hãy dùng runner, config, và helper của dự án.
7
+
8
+ ## Phạm vi
9
+
10
+ - Giữ số test e2e ít và tập trung vào các hành trình người dùng then chốt: đăng nhập, luồng
11
+ tạo/đọc/cập nhật chính, thanh toán hay gửi biểu mẫu, các ranh giới phân quyền.
12
+ - Đẩy các ca biên và biến thể validate xuống tầng test component hoặc unit.
13
+ - Một test chứng minh một hành trình; tránh những script khổng lồ test mọi thứ theo thứ tự.
14
+
15
+ ## Selector
16
+
17
+ Ưu tiên những selector mà người dùng cũng nhận ra, theo thứ tự sau:
18
+
19
+ 1. Vai trò kèm tên truy cập được: `getByRole('button', { name: 'Save' })`.
20
+ 2. Nhãn: `getByLabel('Email')`.
21
+ 3. Chữ thấy được hoặc placeholder cho nội dung không tương tác.
22
+ 4. Một test ID riêng (`data-testid`) khi không có chỗ nắm nào truy cập được, theo
23
+ quy ước của dự án.
24
+
25
+ Tránh class CSS, cấu trúc DOM, nth-child, và XPath; chúng vỡ khi markup
26
+ đổi. Thiếu tên truy cập được thường là một bug accessibility thật; hãy báo lại.
27
+
28
+ ## Chờ theo điều kiện, không ngủ
29
+
30
+ - Không bao giờ dùng thời gian ngủ cố định (`waitForTimeout`, `sleep`) để đồng bộ.
31
+ - Dùng các hành động tự chờ và những assertion ưu tiên web, tự thử lại tới khi một điều kiện
32
+ thành đúng (`expect(locator).toBeVisible()`, `toHaveText`, `toHaveURL`).
33
+ - Chờ đúng phản hồi mạng hay trạng thái UI mà bước kế tiếp phụ thuộc vào.
34
+ - Giữ timeout ở mức mặc định của dự án; nâng timeout lên để test pass là che đi một
35
+ đường đi chậm hoặc đã vỡ.
36
+
37
+ ## Cách ly
38
+
39
+ - Mỗi test tự tạo hoặc tự seed dữ liệu của nó (gọi API, helper seed, hoặc fixture)
40
+ và không dựa vào test khác hay thứ tự chạy.
41
+ - Dùng một context browser mới cho mỗi test; dùng lại trạng thái lưu trữ đã đăng nhập từ một
42
+ bước setup thay vì đăng nhập qua UI mỗi lần, nếu dự án làm vậy.
43
+ - Dùng tên độc nhất (thêm hậu tố là ID của lần chạy) để tránh xung đột khi chạy song song.
44
+ - Dọn dữ liệu đã tạo khi môi trường là dùng chung, hoặc dùng một môi trường
45
+ dùng một lần rồi bỏ.
46
+ - Không dùng chung state thay đổi được ở cấp module giữa các test.
47
+
48
+ ## Phụ thuộc bên ngoài
49
+
50
+ - Thay thế các dịch vụ bên thứ ba (thanh toán, email, bản đồ, analytics) ở tầng mạng
51
+ hoặc trỏ chúng tới các chế độ sandbox mà dự án đã dùng.
52
+ - Không bao giờ gửi email, SMS, hay thanh toán thật từ test.
53
+ - Kiểm soát thời gian và tính ngẫu nhiên ở nơi app cho phép (mock đồng hồ, dữ liệu có seed).
54
+
55
+ ## Assertion
56
+
57
+ - Khẳng định các kết quả người dùng thấy được: chữ, URL, trạng thái bật, một dòng xuất hiện.
58
+ - Khẳng định là không có toast lỗi hay lỗi console, khi dự án cũng làm vậy.
59
+ - Tránh khẳng định layout chính xác tới từng pixel trong test chức năng; đó là việc của test thị giác.
60
+
61
+ ## Kiểm thị giác và accessibility
62
+
63
+ - Snapshot thị giác: khung nhìn, font, và dữ liệu ổn định; che các vùng động (ngày,
64
+ ảnh đại diện); tắt hoạt họa. Hãy xem lại mọi khác biệt snapshot trước khi chấp nhận nó.
65
+ - Snapshot khác nhau giữa các OS và bản build browser; hãy sinh mốc cơ sở trong cùng
66
+ môi trường mà CI dùng.
67
+ - Quét accessibility (kiểu axe) trên các trang và trạng thái chính, gồm cả dialog đang mở.
68
+ Coi chúng là mức sàn, không phải bằng chứng đã đạt accessibility.
69
+
70
+ ## Gỡ lỗi và trace
71
+
72
+ - Bật trace, ảnh chụp, hay video khi fail hoặc ở lần retry đầu, theo config của dự án.
73
+ - Đọc trace trước khi sửa test: xác định bước nào, trạng thái DOM, và các
74
+ lệnh gọi mạng tại thời điểm fail.
75
+ - Tái hiện sự chập chờn bằng cách chạy lặp lại (`--repeat-each` hoặc tương đương) và với
76
+ nhiều worker song song; ghi lại tỉ lệ fail.
77
+ - Retry trong CI có thể tồn tại như một chính sách; một test cần tới chúng thì vẫn là chập chờn và phải
78
+ chuyển sang bug-loop.
79
+
80
+ ## Chạy test
81
+
82
+ - Chạy trên một server cục bộ hay bản build preview, khởi động theo đúng cách dự án làm
83
+ (config web-server của runner hoặc một script).
84
+ - Chạy headless trong CI, và chạy có giao diện hoặc kèm inspector ở cục bộ khi gỡ lỗi.
85
+ - Chạy đúng những browser mà dự án nhắm tới; không thêm browser mà không có quyết định.
@@ -0,0 +1,85 @@
1
+ # Test hiệu năng và test tải
2
+
3
+ Đọc khi chạy mốc hiệu năng cơ sở, ngân sách, hay test tải.
4
+
5
+ Ví dụ dùng script kiểu k6 cho phần tải và audit kiểu Lighthouse cho hiệu năng
6
+ trang; Artillery, Gatling, Locust, hay WebPageTest là tương đương. Hãy dùng
7
+ những công cụ dự án đã có.
8
+
9
+ ## Xin phép trước đã
10
+
11
+ - Không bao giờ test tải hay gây áp lực lên production, một môi trường staging dùng chung, hay bất kỳ
12
+ API bên thứ ba nào mà không có phép tường minh của chủ sở hữu, nêu rõ đích,
13
+ khung thời gian, và mức tải tối đa.
14
+ - Dồn tải lên dịch vụ bên thứ ba (thanh toán, email, bản đồ) có thể vi phạm điều khoản của họ
15
+ và tốn tiền; hãy stub chúng hoặc dùng sandbox của họ với các giới hạn của nó.
16
+ - Một test tải có thể trông như một cuộc tấn công với nhà cung cấp hosting; chủ sở hữu là người lo
17
+ việc thông báo nếu cần.
18
+ - Đích mặc định: một bản build cục bộ hoặc một môi trường test riêng mà bạn kiểm soát.
19
+ - Dừng ngay nếu lỗi vọt lên trên một môi trường dùng chung hoặc có người dùng khác bị
20
+ ảnh hưởng, và báo lại.
21
+
22
+ ## Xác định câu hỏi
23
+
24
+ - Nêu rõ bạn đang đo cái gì và vì sao: kiểm hồi quy, ước lượng năng lực,
25
+ độ trễ dưới mức tải dự kiến, hay chạy dài để tìm rò rỉ.
26
+ - Chọn loại test: smoke (tải rất nhỏ, kiểm chính script), load (lưu lượng dự kiến),
27
+ stress (vượt mức dự kiến, tìm điểm vỡ), spike (bùng lên đột ngột), soak
28
+ (tải đều trong thời gian dài).
29
+ - Dùng tình huống thực tế: đúng tỉ lệ pha trộn endpoint và hành trình người dùng mà lưu lượng thật
30
+ có, thời gian nghĩ giữa các bước, payload và lượng dữ liệu thực tế.
31
+
32
+ ## Mốc cơ sở
33
+
34
+ - Đo một mốc cơ sở trên bản main hay bản release hiện tại, trong cùng môi trường,
35
+ trước khi test một thay đổi.
36
+ - Giữ điều kiện giống nhau giữa các lần chạy: cỡ môi trường, lượng dữ liệu, chế độ
37
+ build, cấu hình mạng, cache nóng hay nguội, thời lượng test.
38
+ - Chạy nhiều hơn một lần; báo cả độ phân tán, không chỉ một lần chạy tốt nhất.
39
+ - Ghi lại điều kiện cùng với mỗi kết quả để có thể tái hiện.
40
+
41
+ ## Chỉ số
42
+
43
+ - Server và API: các phân vị độ trễ (p50, p95, p99) thay vì giá trị trung bình,
44
+ thông lượng, tỉ lệ lỗi, và độ bão hòa (CPU, bộ nhớ, kết nối, độ sâu hàng đợi) nếu
45
+ quan sát được.
46
+ - Hiệu năng trang: Core Web Vitals (LCP, INP, CLS), thời gian tới byte đầu tiên, tổng
47
+ kích thước truyền, và các task dài, dưới một cấu hình thiết bị và mạng đã nêu rõ.
48
+ - Tách giới hạn của công cụ phía client khỏi giới hạn của server; một máy phát tải đang 100% CPU
49
+ cho ra những con số vô nghĩa.
50
+
51
+ ## Ngân sách và ngưỡng
52
+
53
+ - Dùng ngân sách mà dự án đã định ra (kích thước bundle, LCP, độ trễ p95, tỉ lệ lỗi).
54
+ - Nếu chưa có, hãy báo các giá trị đo được và đề xuất ngân sách cho chủ sở hữu; đừng
55
+ tự nghĩ ra ngưỡng pass/fail rồi trình bày chúng như yêu cầu.
56
+ - Mã hóa các ngưỡng đã thống nhất vào cơ chế threshold của công cụ, để một lần chạy fail
57
+ một cách khách quan.
58
+
59
+ ## Script
60
+
61
+ - Giữ script trong thư mục test của dự án, theo quy ước của dự án.
62
+ - Tham số hóa URL đích, số người dùng, và thời lượng qua biến môi trường;
63
+ mặc định trỏ tới đích cục bộ hay đích test, không bao giờ production.
64
+ - Dùng tài khoản test và dữ liệu tổng hợp; không bao giờ dùng thông tin đăng nhập thật. Tạo và dọn
65
+ dữ liệu test mà lần chạy đó cần.
66
+ - Kiểm cả phản hồi (status, một field quan trọng), không chỉ kiểm là request đã trả về;
67
+ lỗi nhanh trông giống như độ trễ tốt.
68
+ - Tăng tải dần dần; có một chặng smoke ngắn trước khi vào tải đầy.
69
+
70
+ ## Đọc hiểu kết quả
71
+
72
+ - So với mốc cơ sở trong cùng điều kiện; coi những chênh lệch nằm trong
73
+ độ phân tán giữa các lần chạy là nhiễu.
74
+ - Tìm chỗ độ trễ bắt đầu bật lên khi tải tăng; đó là giới hạn năng lực.
75
+ - Đối chiếu với chỉ số và log của server ở nơi có, để xác định điểm nghẽn,
76
+ rồi giao việc chẩn đoán cho bug-loop hoặc cho skill phụ trách (databases,
77
+ backend-development, frontend-development).
78
+
79
+ ## Báo cáo
80
+
81
+ - Môi trường đích và tham chiếu tới việc cho phép, công cụ và phiên b��n, tình huống, cấu hình
82
+ tải, thời lượng, lượng dữ liệu.
83
+ - Kết quả mốc cơ sở và kết quả mới kèm các phân vị, tỉ lệ lỗi, và độ phân tán.
84
+ - Các quan sát về điểm nghẽn, có ghi rõ là bằng chứng hay là suy luận.
85
+ - Những gì chưa chạy và vì sao.
@@ -0,0 +1,78 @@
1
+ # Test bảo mật cơ bản
2
+
3
+ Đọc khi chạy audit phụ thuộc, kiểm header, hay test luồng auth.
4
+
5
+ Phần này nói về các kiểm tra an toàn, thường lệ, trong môi trường test. Review bảo mật của code hay
6
+ thiết kế thuộc về security-review. Viết mã khai thác, kiểm thử xâm nhập, và
7
+ quét những hệ thống bạn không sở hữu đều nằm ngoài phạm vi.
8
+
9
+ ## Việc cho phép và an toàn
10
+
11
+ - Chỉ test những môi trường chủ sở hữu đã cho phép: cục bộ, CI, hoặc một bản
12
+ deploy test riêng. Không bao giờ test production hay hệ thống bên thứ ba mà không có văn bản
13
+ cho phép tường minh, nêu rõ đích và các kiểm tra được phép.
14
+ - Chỉ dùng tài khoản test và dữ liệu tổng hợp. Không đọc, in ra, hay lưu secret,
15
+ token, hay dữ liệu cá nhân thật.
16
+ - Dùng các kiểm tra không phá hoại. Không chạy scanner hung hãn, fuzzer, hay
17
+ công cụ dò vét cạn, trừ khi chủ sở hữu đã cho phép dùng chúng trên đích đó.
18
+ - Nếu một kiểm tra phát hiện một lỗ hổng thật, hãy dừng việc thăm dò nó, ghi lại các bước
19
+ tái hiện tối thiểu, và báo lên trên một cách riêng tư; không dán chi tiết khai thác
20
+ hay secret vào log dùng chung.
21
+
22
+ ## Audit phụ thuộc
23
+
24
+ - Chạy công cụ audit có sẵn của trình quản lý package (ví dụ `npm audit`, `pnpm audit`,
25
+ `pip-audit`, `govulncheck`) hoặc scanner mà dự án đã dùng. Không
26
+ cài scanner mới mà không có quyết định.
27
+ - Báo lại: package, phiên bản đã cài, cảnh báo bảo mật, mức nghiêm trọng, đường chạy code có lỗ hổng
28
+ có với tới được hay không nếu biết, và phiên bản đã sửa.
29
+ - Không chạy các lệnh tự động sửa để nâng cấp phụ thuộc; nâng cấp là một
30
+ thay đổi riêng, phải được chủ sở hữu chấp thuận và có test riêng của nó.
31
+ - Ghi riêng các phụ thuộc chỉ dùng khi dev, tách khỏi phụ thuộc lúc chạy.
32
+
33
+ ## Kiểm header HTTP
34
+
35
+ Gửi request tới các trang chính và các phản hồi API từ môi trường test rồi kiểm:
36
+
37
+ - `Strict-Transport-Security` trên các phản hồi HTTPS.
38
+ - `Content-Security-Policy` có mặt và không có `unsafe-inline` rộng hay nguồn script
39
+ dạng ký tự đại diện, theo chính sách của dự án.
40
+ - `X-Content-Type-Options: nosniff`.
41
+ - Kiểm soát việc nhúng khung: CSP `frame-ancestors` hoặc `X-Frame-Options`.
42
+ - `Referrer-Policy` đã được đặt.
43
+ - Cookie cho session: `Secure`, `HttpOnly`, và một `SameSite` phù hợp.
44
+ - CORS: không có origin dạng ký tự đại diện đi kèm thông tin đăng nhập; các origin được phép khớp với danh sách
45
+ đã định.
46
+ - Không có header tiết lộ phiên bản hay stack trace trong các phản hồi lỗi.
47
+
48
+ Hãy viết những cái này thành test tự động (test e2e hay test API) khi dự án muốn giữ chúng lại.
49
+
50
+ ## Test luồng xác thực
51
+
52
+ - Truy cập chưa đăng nhập vào trang và API được bảo vệ thì bị từ chối hoặc bị chuyển hướng.
53
+ - Người dùng A không đọc hay sửa được tài nguyên của người dùng B bằng cách đổi một ID (IDOR).
54
+ - Một người dùng không có vai trò thì không tới được trang admin hay gọi được API admin trực tiếp, chứ không
55
+ phải chỉ chặn bằng cách ẩn nút.
56
+ - Logout làm session mất hiệu lực; cookie hay token session cũ thôi hoạt động.
57
+ - Token đã hết hạn hoặc bị can thiệp thì bị từ chối.
58
+ - Token đặt lại mật khẩu chỉ dùng được một lần và có hết hạn.
59
+ - Endpoint đăng nhập và đặt lại mật khẩu có giới hạn tần suất với các lần thử lặp lại (hãy test bằng một số nhỏ
60
+ request, không phải một lượt dò vét cạn).
61
+ - Thông báo lỗi không tiết lộ việc một tài khoản có tồn tại hay không, theo chính sách của dự án.
62
+ - Request làm đổi state phải có bảo vệ CSRF khi việc xác thực dựa vào cookie.
63
+
64
+ ## Kiểm việc xử lý dữ liệu nhập
65
+
66
+ - Dữ liệu người dùng nhập được phản chiếu lại thì phải được escape trong trang đã render (hãy gửi một dấu hiệu vô hại,
67
+ ví dụ một chuỗi có dấu ngoặc nhọn và dấu nháy, rồi kiểm xem nó render ra như chữ).
68
+ - Tải file lên thì từ chối các loại không được phép và file quá lớn.
69
+ - Tham số chuyển hướng chỉ nhận những đích được phép.
70
+ - API từ chối những field ngoài dự kiến có thể đặt được các thuộc tính đặc quyền.
71
+
72
+ ## Báo cáo
73
+
74
+ - Môi trường đã test và việc cho phép tương ứng.
75
+ - Từng kiểm tra: pass, fail, hay chưa chạy kèm lý do.
76
+ - Các phát hiện kèm mức nghiêm trọng, endpoint hay trang bị ảnh hưởng, cách tái hiện tối thiểu, và một
77
+ chủ sở hữu được gợi ý (backend-development, frontend-development, hay security-review).
78
+ - Các cảnh báo bảo mật của phụ thuộc kèm đường nâng cấp, nhưng không tự áp dụng chúng.
@@ -0,0 +1,78 @@
1
+ # Test unit và component
2
+
3
+ Đọc khi viết test unit hay component, mock, hay snapshot cho code web.
4
+
5
+ Ví dụ dùng Vitest hoặc Jest với truy vấn kiểu Testing Library; Vue Test Utils,
6
+ Svelte Testing Library, và Angular TestBed có cái tương đương. Hãy dùng runner,
7
+ môi trường (jsdom, happy-dom, hay chế độ browser thật), và file setup của dự án.
8
+
9
+ ## Test unit
10
+
11
+ - Nhắm vào logic thuần: định dạng, parse, validate, reducer, máy trạng thái,
12
+ selector, hàm tiện ích.
13
+ - Ca dạng bảng cho các biến thể dữ liệu nhập; gồm cả giá trị biên, giá trị rỗng, và
14
+ dữ liệu nhập không hợp lệ.
15
+ - Không cần DOM hay mạng; nếu một test unit cần nhiều mock, có thể code cần một
16
+ đường tách, hoặc test đó thuộc về một tầng khác.
17
+ - Kiểm soát thời gian và tính ngẫu nhiên bằng fake timer của runner hoặc đồng hồ được tiêm vào;
18
+ khôi phục chúng sau mỗi test.
19
+
20
+ ## Test component
21
+
22
+ - Render component với props thực tế và các provider nó cần (router,
23
+ theme, query client, i18n) qua một helper test dùng chung nếu dự án có.
24
+ - Tương tác như một người dùng: gõ chữ, bấm, và hành động bàn phím kiểu user-event
25
+ chứ không phát ra các event tổng hợp ở tầng thấp.
26
+ - Truy vấn theo vai trò, nhãn, và chữ; chỉ dùng test ID khi không có gì truy cập được.
27
+ - Khẳng định những gì người dùng thấy hoặc những gì component phát ra, không khẳng định state nội bộ,
28
+ phương thức của instance, hay hook riêng tư.
29
+ - Bao phủ từng trạng thái thấy được: loading, rỗng, lỗi, thành công, disabled, và lỗi
30
+ validate.
31
+ - Dùng truy vấn bất đồng bộ (`findBy...`, `waitFor`) cho các cập nhật bất đồng bộ; không bao giờ dùng
32
+ khoảng chờ cố định.
33
+
34
+ ## Mock
35
+
36
+ - Mock ở các biên: mạng (mock ở mức request, như handler kiểu MSW
37
+ hoặc công cụ của dự án), timer, các API browser mà môi trường test không có.
38
+ - Ưu tiên một mock thực tế của tầng HTTP hơn là mock từng module mà component
39
+ import.
40
+ - Không mock chính unit đang được test hay mock bản thân framework.
41
+ - Reset mock và handler giữa các test; những request không được xử lý và ngoài dự kiến thì nên làm
42
+ test fail.
43
+ - Giữ dữ liệu mock sát với hình dạng API thật, tốt nhất là lấy từ type hay fixture dùng chung.
44
+
45
+ ## Snapshot
46
+
47
+ - Tránh snapshot DOM lớn; chúng vỡ khi markup đổi dù chẳng liên quan, và rồi bị
48
+ chấp nhận mà không ai review.
49
+ - Dùng snapshot inline nhỏ cho những output serialize ổn định (một chuỗi đã định dạng, một
50
+ config được sinh ra).
51
+ - Hãy review mọi thay đổi snapshot như một thay đổi hành vi trước khi cập nhật nó.
52
+
53
+ ## Cách ly và vệ sinh
54
+
55
+ - Mỗi test tự dựng state của nó; không phụ thuộc thứ tự.
56
+ - Dọn các component đã render, timer, và thay đổi toàn cục (runner thường tự
57
+ dọn; hãy kiểm lại với các setup tự tạo).
58
+ - Không dùng mạng thật, không ghi file ngoài thư mục tạm, không có secret thật.
59
+ - Giữ test nhanh; bộ test chậm sẽ bị bỏ qua. Đánh dấu test chậm theo cách dự án làm.
60
+
61
+ ## Độ bao phủ
62
+
63
+ - Dùng báo cáo coverage để tìm những nhánh chưa được test trong code đã đổi, không dùng nó như một
64
+ chỉ tiêu phải đạt. Không thêm test không có assertion để nâng con số.
65
+
66
+ ## Lưu ý về môi trường
67
+
68
+ - jsdom và những môi trường tương tự không có layout, không có CSS thật, và thiếu một số API
69
+ (IntersectionObserver, ResizeObserver, matchMedia); hãy stub chúng trong setup hoặc test
70
+ những hành vi phụ thuộc layout trên browser thật (e2e hoặc chế độ browser).
71
+ - Server component hay loader của framework có thể cần chính tiện ích test của
72
+ framework hoặc cần một test e2e; hãy xem tài liệu framework cho phiên bản đã cài.
73
+
74
+ ## Accessibility trong test component
75
+
76
+ - Truy vấn theo vai trò vốn đã phát hiện được việc thiếu tên và thiếu vai trò.
77
+ - Nếu dự án dùng một matcher kiểu axe, hãy chạy nó trên các trạng thái đã render với dialog
78
+ và menu đang mở.
@@ -1,8 +1,8 @@
1
1
  {
2
- "main": ["goal-griller", "xia", "sequence-execution-plan", "prompt-leverage", "bug-loop", "smart-commits", "compact", "curate"],
3
- "lead": ["xia", "sequence-execution-plan", "prompt-leverage", "bug-loop", "smart-commits"],
4
- "peer": ["xia", "bug-loop", "smart-commits"],
2
+ "main": ["goal-griller", "xia", "sequence-execution-plan", "prompt-leverage", "bug-loop", "smart-commits", "compact", "curate", "skill-authoring", "architecture-docs", "feature-architecture", "test-strategy", "safe-refactor", "security-review", "release-readiness"],
3
+ "lead": ["xia", "sequence-execution-plan", "prompt-leverage", "bug-loop", "smart-commits", "architecture-docs", "feature-architecture", "test-strategy", "safe-refactor", "security-review", "release-readiness"],
4
+ "peer": ["xia", "bug-loop", "smart-commits", "feature-architecture", "test-strategy", "safe-refactor"],
5
5
  "oracle": [],
6
- "reviewer": [],
6
+ "reviewer": ["security-review", "release-readiness"],
7
7
  "supervisor": []
8
8
  }