@educa-corp/sdd-framework 0.1.0

package/commands/dev-smoke-test.tmpl

@@ -0,0 +1,217 @@
+# /dev-smoke-test — Smoke Test Service hoặc App đang chạy
+
+Dùng khi service/app **đang chạy sẵn**. Khác `/dev-run-test` (không cần live server).
+
+## Gate
+{{include:steps/gate.md}}
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID từ `$ARGUMENTS`. Context loading cung cấp `conventions.service_run`, thông tin port, và `tech_stack.module`.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Service Detection
+
+Đọc `active_module` từ context. Dùng để chọn đúng cách dev-smoke-test.
+
+| Platform | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+---
+
+## Nếu `platform_type = backend`
+
+### Phase 1 — Xác minh service đang chạy
+
+Đọc `conventions.service_run` từ project-context.yaml để xác định port.
+
+```bash
+# Try common health endpoints (use whichever applies):
+curl -s http://localhost:{port}/health            # generic / Go / Node
+curl -s http://localhost:{port}/actuator/health   # Spring Boot
+curl -s http://localhost:{port}/ping              # some frameworks
+```
+
+Nếu chưa chạy → "Khởi động với `{conventions.service_run}` từ project root."
+
+### Phase 2 — Xác định endpoint
+
+Từ UC-ID → tìm controller/handler có `@trace.implements={UC-ID}`.
+Liệt kê: method, path, auth/role bắt buộc.
+
+### Phase 3 — Lấy auth token (nếu cần)
+
+```
+Endpoint yêu cầu auth. Lựa chọn:
+1. Dán Bearer token (từ Postman/DevTools)
+2. Dùng test/dev token từ local config
+3. Skip — chỉ test endpoint public
+```
+
+### Phase 4 — Run
+
+```bash
+# GET
+curl -s -X GET "http://localhost:{port}/v1/{resource}" \
+  -H "Authorization: Bearer {token}" | {JSON_FORMATTER}
+
+# POST
+curl -s -X POST "http://localhost:{port}/v1/{resource}" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{"field1": "test_value"}'
+```
+
+| Kết quả | Ý nghĩa |
+|--------|---------|
+| 200/201 + đúng data | ✅ OK |
+| 200 + sai data | ⚠️ Logic bug → /debug |
+| 400 | Sai request body → kiểm tra field bắt buộc |
+| 401 | Token hết hạn hoặc sai config |
+| 403 | Sai role → kiểm tra auth rule |
+| 500 | Server error → /debug |
+| Connection refused | Service chưa chạy |
+
+### Nếu `active_module = context-engineering`
+
+#### Phase 1 — Xác minh entry point của pipeline tới được
+
+Chạy prompt function trực tiếp với một input hợp lệ tối thiểu:
+
+```bash
+# Python (pytest / script):
+python -c "from {module}.{function} import {function}; print({function}(input='{test_input}'))"
+
+# Or using the project test command with a smoke marker:
+{conventions.test_command} -m smoke -v
+```
+
+#### Phase 2 — Xác minh cấu trúc output
+
+Kiểm tra output khớp schema kỳ vọng:
+
+```
+Expected output schema: {output fields from @trace or tech-doc}
+Actual output: {paste output here}
+```
+
+#### Phase 3 — Diễn giải kết quả
+
+| Kết quả | Ý nghĩa |
+|--------|---------|
+| Output khớp schema | ✅ OK |
+| Output có nhưng sai format | ⚠️ Logic bug → /debug |
+| `APIError` / `AuthenticationError` | API key không hợp lệ hoặc service unavailable |
+| `TokenLimitError` | Input quá dài — kiểm tra kích thước prompt template |
+| Exception / traceback | Lỗi code → /debug |
+
+---
+
+## Nếu `platform_type = web-frontend`
+
+### Phase 1 — Xác minh dev server đang chạy
+
+```bash
+# Linux / macOS:
+curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}
+
+# Windows (cmd / PowerShell):
+curl -s -o NUL -w "%{http_code}" http://localhost:{port}
+
+# Should return 200. If not: start with {conventions.service_run} (e.g., npm run dev)
+```
+
+### Phase 2 — Chạy E2E smoke test
+
+Xác định E2E tool trong dự án (Playwright hoặc Cypress):
+
+```bash
+# Playwright — run scenarios tagged with this UC:
+npx playwright test --grep "{UC-ID}"
+
+# Cypress:
+npx cypress run --spec "cypress/e2e/{UC-ID}*"
+```
+
+Nếu chưa có E2E test → mở browser và verify thủ công:
+1. Điều hướng tới route của UC này
+2. Thực hiện hành động chính của người dùng
+3. Xác nhận kết quả kỳ vọng hiển thị
+
+### Phase 3 — Diễn giải kết quả
+
+| Kết quả | Ý nghĩa |
+|--------|---------|
+| Tất cả E2E test pass | ✅ OK |
+| Assertion failed | ⚠️ Logic bug → /debug |
+| `ERR_CONNECTION_REFUSED` | Dev server chưa chạy |
+| API trả về 4xx/5xx | Vấn đề backend → kiểm tra backend service |
+
+---
+
+## Nếu `platform_type = mobile`
+
+### Phase 1 — Xác minh device/emulator sẵn sàng
+
+```bash
+# Flutter:
+flutter devices              # list connected devices/emulators
+flutter install              # install current build on device
+
+# React Native:
+npx react-native run-android   # build + install on connected Android
+npx react-native run-ios       # build + install on iOS simulator
+
+# Android (Compose):
+./gradlew installDebug         # install APK on connected device/emulator
+
+# iOS (SwiftUI):
+# Open Xcode → select simulator → Product → Run
+```
+
+### Phase 2 — Checklist dev-smoke-test thủ công
+
+Với UC đang test, verify trên device:
+1. Điều hướng tới màn của UC này
+2. Thực hiện hành động chính từ Scenario `.feature` (step `When`)
+3. Xác nhận kết quả kỳ vọng hiển thị (step `Then`)
+4. Kiểm tra có crash hoặc dialog lỗi bất ngờ không
+
+### Phase 3 — Bắt issue nếu phát hiện
+
+```bash
+# Flutter:
+flutter logs
+
+# Android:
+adb logcat -d | grep -i "error\|exception\|crash"
+
+# iOS:
+# Copy crash log from Xcode → Devices and Simulators → View Device Logs
+```
+
+Dán output vào `/debug`.
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/dev-smoke-test Report — {UC-ID}
+Platform: {backend | web-frontend | mobile}
+| Endpoint / Flow       | Status      | Result  |
+|-----------------------|-------------|---------|
+| {method} {path/screen}| ✅/⚠️/❌   | {notes} |
+
+Status legend: ✅ = OK  |  ⚠️ = Responded but wrong data / logic bug  |  ❌ = Error / not running
+
+Issues: {mô tả các failure}
+Next: /debug (dán lỗi tương tác) HOẶC /fix-bug {TICKET_ID} HOẶC sẵn sàng PR
+```