@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/commands/qc-run-test.tmpl

@@ -26,7 +26,19 @@ pytest-playwright script + Page Object, chạy chúng, và report kết quả th
 Quy tắc stack (BẮT BUỘC — từ `modules/qc-playwright/stack-profile.yaml`):
 - Markdown-first: không bao giờ sinh Python khi chưa có `.Test.md` đã review.
 - Page Object extends `BasePage` gọn, 3 lớp: locator `_x()`, action `verb_noun()`, assertion `assert_x()` dùng `expect()`.
-- **Locator từ test-id contract (không scan runtime).** Đọc bảng *Test Selectors* §4.5.6 (block platform) của tech-doc gộp tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (nếu có — bảng gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này**) và dựng mỗi Page Object locator từ test-id ổn định của nó — web `get_by_test_id("...")`, RN `testID`, Flutter `Key`/`Semantics`, native `accessibilityIdentifier`. **Ưu tiên map; fallback** về role/label/text/CSS (scan chậm hơn) chỉ cho một element có action mà **không** có test-id trong §4.5.6 — và ghi chú để gap được thêm vào tech-design.
+- **Locator từ test-id contract (không scan runtime).** Đọc bảng *Test Selectors* §4.5.6 (block platform) của tech-doc gộp tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (nếu có — bảng gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này**) và dựng mỗi Page Object locator từ test-id ổn định của nó. **Ưu tiên map; fallback** về role/label/text/CSS (scan chậm hơn) chỉ cho một element có action mà **không** có test-id trong §4.5.6 — và ghi chú để gap được thêm vào tech-design.
+
+- **TÊN THUỘC TÍNH test-id: đọc `@trace.testid_attr`, KHÔNG tự suy từ platform.**
+  Đọc `@trace.testid_attr` từ **header tech-doc gộp** (do `/map-testids` ghi — nó đã phân giải một lần cho cả feature). Đây là **nửa QC của contract FE↔QC**: `/generate-code` đọc chính field này để emit thuộc tính lên element.
+
+  | Đọc được | Làm gì |
+  |---|---|
+  | web + attr ≠ `data-testid` (vd `data-test` · `data-qa`) | **BẮT BUỘC** cấu hình test-id attribute trước khi dùng `get_by_test_id()`: `playwright.selectors.set_test_id_attribute("{attr}")` (hoặc `testIdAttribute` trong config). Bỏ bước này thì `get_by_test_id()` vẫn dò `data-testid` mặc định → **trượt 100% locator**. |
+  | web + attr = `data-testid` | `get_by_test_id("...")` như thường (đúng mặc định Playwright). |
+  | RN / Flutter / native | Dùng đúng cơ chế mà `{attr}` mô tả (`testID` · `Key`/`Semantics(identifier:)` · `accessibilityIdentifier`). |
+  | **Không tìm thấy field** | **Cảnh báo mềm, KHÔNG im lặng hardcode:** `⚠️ Tech-doc thiếu @trace.testid_attr — fallback theo platform ({attr mặc định}). Nếu FE dùng thuộc tính khác thì MỌI locator sẽ trượt. Chạy /map-testids {UC-ID} để ghi field này.` Rồi mới fallback. |
+
+  > **Vì sao không suy từ platform cho nhanh:** suy từ platform là **phát biểu lại một sự thật đã được ghi ở nơi khác** — đúng lớp lỗi mà `bin/trace-schema.json` sinh ra để chống. Nó hỏng ở đúng ca field này tồn tại để phục vụ: dự án web dùng `data-test`/`data-qa` thay vì mặc định, hoặc một PRD trải ba platform với ba thuộc tính khác nhau. Và nó hỏng **im lặng theo kiểu tệ nhất**: test fail với "element not found" — trông y hệt một bug sản phẩm, nên QC sẽ đi mở bug thay vì sửa selector.
 - pytest-playwright fixture; mỗi test độc lập; gom theo (role, account) để auth không bao giờ xen kẽ.
 - Không hard-code URL/cred/timeout (dùng `Env.*` / `CONFIG[...]`); không `time.sleep()`; không Allure.
 - Phủ **100%** TC trong file — mỗi TC kết thúc Pass/Fail/Skip (không còn Draft).