Web App Test Engineering

Skill Codex chuyên nghiệp để đọc PRD, tài liệu kiến trúc và source code; dựng mô hình hệ thống; sinh test inventory; chạy kiểm thử web app qua browser, API, runner và telemetry; đối chiếu runtime với thiết kế; rồi tạo báo cáo assurance cùng change request dự thảo.

Skill tập trung vào phần khó nhất của kiểm thử sản phẩm: quy tắc nghiệp vụ, trạng thái ẩn, quyền admin, tenant isolation, async jobs, retries, dữ liệu, backend side effects, recovery và bằng chứng đủ mạnh để hỗ trợ quyết định release.

Trạng thái: v1.0.0-beta.1 — public beta. Dùng tốt cho orchestration, test planning, evidence modeling và review chuyên sâu. Chưa nên dùng như release authority tự động duy nhất. Xem Giới hạn hiện tại.

Mục Tiêu

Một web app có thể hiển thị đúng nhưng vẫn sai ở tầng nghiệp vụ hoặc backend:

Toast báo thành công nhưng dữ liệu không được lưu.
API trả 200 hoặc 202 nhưng job downstream thất bại.
UI ẩn nút nhưng backend vẫn cho phép hành động trái quyền.
Retry tạo giao dịch, entitlement hoặc webhook trùng lặp.
Source hiện tại khác artifact đang deploy.
Feature flags, config hoặc migrations làm runtime khác tài liệu.
Rerun pass che race condition hoặc session contamination.
CI exit 0 nhưng shard không chạy test nào.

Skill biến các rủi ro này thành run contract, evidence graph, state machine, test inventory, safety gate, correlation packet, finding và release report.

Nguyên Tắc Cốt Lõi

Evidence-first: mọi claim quan trọng phải liên kết bằng chứng có provenance.
Risk-bounded: sinh inventory rộng, nhưng chỉ chạy subset theo risk, change impact và budget.
Fail-closed: thiếu target, identity, oracle, evidence hoặc safety thì không được PASS.
Four-plane model: tách normative intent, executable definition, deployed reality và observed execution.
Human release authority: Skill đề xuất verdict; con người giữ quyền release và waiver.
Production read-only: mutation, payment, email, SMS và external effects cần allowlist cùng approval rõ.
Không suy diễn root cause: timestamp gần nhau, toast, HTTP status hoặc log cuối không đủ chứng minh causality.

Khả Năng Chính

1. Tự Rà Soát Repository Và Tài Liệu

PRD, acceptance criteria, README, specs.
ADR, architecture diagrams, SLO và runbooks.
Routes, controllers, services, domain rules.
API/event schemas, migrations và constraints.
RBAC, permissions, feature flags và tenancy.
Queues, jobs, webhooks, retries, DLQ và reconciliation.
Existing tests, fixtures, selectors, telemetry và CI.
CodeGraph-first khi repository có .codegraph/.

2. Dựng Mô Hình Nghiệp Vụ Và Kiến Trúc

Workflow state machines.
Business rules và forbidden transitions.
Data invariants và transaction boundaries.
Role/permission/tenant matrices.
Async delivery, ordering, dedupe và consistency deadlines.
Admin recovery, audit và operational controls.
Temporal evidence graph bốn plane.

3. Sinh Test Inventory Có Truy Vết

Mỗi case có:

Requirement, risk và source IDs.
Actor, journey, precondition và action path.
Oracle, terminal business state và forbidden effect.
Hazard/action class.
Data/cleanup ownership.
Required evidence types.
Automation và execution status.

Skill không tạo full Cartesian product. Planner dùng priority, risk score, dedup, constraint, budget và pairwise selection.

4. Điều Phối Thực Thi

Browser plugin cho interactive reconnaissance và session có sẵn.
Browser sentinel probe mặc định không mutation.
Project-native runner cho regression/release evidence.
Playwright fallback khi phù hợp.
API/backend adapters theo access mode.
Correlation browser → request → trace → message/job → webhook → datastore.

5. Review UI Đến Backend

UI states, accessibility, navigation và error recovery.
Network/API schema, semantics, authorization và idempotency.
Logs, metrics, traces, queue/job state và audit records.
Architecture conformance và deployment/configuration drift.
Admin, async failure, reconciliation và recovery.

6. Báo Cáo Và Change Request

Decision summary một trang.
Machine-readable evidence bundle.
Finding đa nhãn.
Severity và confidence tách riêng.
Retest và waiver lifecycle.
Developer change request ở trạng thái DRAFT.

Kiến Trúc Assurance

flowchart LR
    A["Normative intent<br/>PRD · ADR · contracts"] --> E["Evidence graph"]
    B["Executable definition<br/>source · schema · tests"] --> E
    C["Deployed reality<br/>artifact · config · flags"] --> E
    D["Observed execution<br/>browser · API · trace · state"] --> E
    E --> F["Risk-based inventory"]
    F --> G["Bounded execution plan"]
    G --> H["Oracle + correlation"]
    H --> I["Findings + conformance"]
    I --> J["Release report + DRAFT change request"]

Chi tiết: Kiến trúc và mô hình dữ liệu.

Access Modes

Mode	Nguồn được phép dùng	Boundary
`black-box`	UI, public API, public docs	Không dùng source, DB, queue hoặc internal endpoint làm oracle
`gray-box`	Black-box cộng repo, config, fixtures và logs được cấp quyền	Business outcome vẫn cần public/user-visible oracle
`white-box`	Gray-box cộng DB, queue, internal API, flags và server telemetry	Tách internal oracle khỏi user-visible oracle

Nếu đọc repository, run tối thiểu là gray-box.

Profiles

Profile	Mục đích
`smoke`	P0 entry points, auth và core surfaces
`workflow`	Journey nghiệp vụ, branches, async terminal state và cleanup
`release`	P0, risk-ranked P1, auth boundaries và pairwise matrix
`incident`	Reproduction/falsification, bảo toàn evidence
`architecture`	Contract, trust boundary, resilience và observability
`regression`	Original repro, fixed path, neighboring boundary và negative case

Outcomes Chuẩn

PASS
FAIL_PRODUCT
FAIL_TEST_HARNESS
FLAKY
BLOCKED
INCONCLUSIVE
ABORTED_SAFETY

HTTP 2xx, toast, queue acknowledgement, screenshot hoặc console sạch không đủ làm business oracle đơn độc. Pass-after-retry phải là FLAKY. 0 matched tests hoặc all-skipped phải là FAIL_TEST_HARNESS.

Cài Đặt

Cách 1 — Clone Repository

git clone https://github.com/buithanhninh/web-app-test-engineering.git

Cách 2 — Cài Vào Codex Trên Windows

$source = Resolve-Path .\web-app-test-engineering
$destination = Join-Path $env:USERPROFILE '.codex\skills\web-app-test-engineering'
Copy-Item -Path $source -Destination $destination -Recurse

Cách 3 — Cài Vào Codex Trên macOS/Linux

mkdir -p ~/.codex/skills
cp -R web-app-test-engineering ~/.codex/skills/web-app-test-engineering

Sau khi cài, gọi:

Use $web-app-test-engineering để đọc PRD, source và kiến trúc của repository này, lập full test inventory theo risk, chạy các test khả thi và tạo báo cáo assurance.

Quick Start

Tạo QA Workspace

python scripts/init_qa_workspace.py ./qa-run --profile release

Lập Execution Plan

python scripts/plan_qa_execution.py \
  ./qa-run/03-execution/executable-test-inventory.csv \
  ./qa-run/03-execution/execution-plan.csv \
  --profile release \
  --json

Validate

python scripts/validate_qa_workspace.py ./qa-run --json

Chấm Assurance

python scripts/score_qa.py ./qa-run --json --enforce

Render Report

python scripts/render_qa_report.py ./qa-run \
  --output ./qa-run/05-reports/release-assurance-report.md \
  --json-output ./qa-run/05-reports/release-assurance-report.json

Các script chỉ dùng Python standard library. YAML templates dùng JSON syntax hợp lệ theo YAML 1.2.

Ví Dụ Prompt

Release Review

Use $web-app-test-engineering ở profile release.
Đọc PRD, ADR, source, migrations, permissions và existing tests.
Dựng business state machines, full test inventory và execution subset theo risk.
Chạy Browser sentinel probe, native test runner và API checks phù hợp.
Tạo release assurance report, findings và DRAFT change requests.

Workflow Review

Use $web-app-test-engineering để kiểm workflow checkout từ UI tới payment job, ledger, entitlement, webhook và recovery.
Không coi HTTP 202 hoặc toast success là business completion.

Regression Review

Use $web-app-test-engineering để verify fix cho bug cross-tenant authorization.
Chạy original repro, fixed path, session transitions, neighboring negative cases và cleanup exact-ID.

Architecture Review

Use $web-app-test-engineering ở profile architecture.
So sánh PRD/ADR, source, deployed artifact, config/flags và runtime telemetry.
Ghi CONFORMANT, NON_CONFORMANT, PARTIALLY_OBSERVED, CONFLICTING_EVIDENCE hoặc UNKNOWN.

Artifact Được Tạo

00-run/         Run contract và environment identity
01-evidence/    Sources, conflicts, evidence và artifact manifests
02-model/       System model, risks, rules, invariants, states, permissions, async
03-execution/   Test data, inventory, execution plan, run/correlation/cleanup receipts
04-assurance/   Findings, conformance, retest, waivers và remediation backlog
05-reports/     Release report và developer change request

Repo cung cấp 28 templates, 15 references và 5 deterministic tools cộng unit tests.

Cấu Trúc Repository

SKILL.md
agents/openai.yaml
assets/
  profile-templates.json
  template-manifest.json
  templates/
references/
scripts/
README.md
CHANGELOG.md
CONTRIBUTING.md
SECURITY.md
LICENSE
VERSION

Kiểm Thử Và Chất Lượng

Bản v1.0.0-beta.1 đã được xác minh:

20/20 unit/regression tests.
Official Skill validator: pass.
Python compile: pass.
CLI smoke: 6/6 profiles.
Forward pressure scenarios: 3/3.
ZIP/source parity được kiểm tra khi tạo release asset.

Lệnh kiểm tra:

python -B scripts/test_tools.py
python -B /path/to/skill-creator/scripts/quick_validate.py .

Chi tiết: Xác minh chất lượng.

Giới Hạn Hiện Tại

Bản beta chưa phải autonomous universal tester hoặc release authority hoàn chỉnh. Các giới hạn lớn:

Pass gates vẫn còn phần dựa trên receipt do agent/harness cung cấp.
Planner chưa tự đọc production safety manifest.
Browser/native runner adapters chưa được đóng gói thành execution engine thống nhất.
Forward tests hiện tập trung vào reasoning scenarios, chưa có benchmark web app đầy đủ.
Formal schema/version migration và cross-platform CI cần hoàn thiện thêm.

Xem danh sách đầy đủ và mức ưu tiên: Giới hạn hiện tại.

Roadmap

Computed gate-receipt engine thay self-attested pass flag.
Safety-aware planner đọc environment/action policy.
Strict artifact existence/hash/evidence-type validation.
Waiver expiry và release-scope enforcement.
Executable fixture web app cho browser/API/backend benchmark.
Native Playwright/Cypress/JUnit adapters.
Property tests, fuzz tests và CI Windows/Linux/macOS.

Chi tiết: Roadmap.

An Toàn Và Phạm Vi Hợp Pháp

Chỉ kiểm thử hệ thống thuộc sở hữu hoặc được cấp quyền rõ ràng. Không dùng Skill để:

Bypass authentication hoặc authorization.
Lấy secret, token hoặc dữ liệu trái phép.
Mutation production ngoài policy.
Gửi payment, email, SMS hoặc webhook thật ngoài sandbox/allowlist.
Auto-submit ticket, auto-waive risk hoặc tự quyết định release khi policy chưa cho phép.

Thiếu quyền hoặc evidence: ghi BLOCKED, INCONCLUSIVE hoặc ABORTED_SAFETY; không phỏng đoán.

Đóng Góp

Đọc CONTRIBUTING.md. Pull request nên có:

Vấn đề hoặc failure mode cụ thể.
Test fail trước thay đổi.
Implementation nhỏ, deterministic.
Unit/pressure test chứng minh loophole đã được đóng.
Không hạ safety, evidence hoặc release gates.

Bảo Mật

Không đăng token, HAR chưa redact, session storage hoặc dữ liệu production trong issue công khai. Đọc SECURITY.md.

Giấy Phép

Phát hành theo MIT License.

Name		Name	Last commit message	Last commit date
agents		agents
assets		assets
docs		docs
references		references
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SKILL.md		SKILL.md
VERSION		VERSION

Latest commit

History

Folders and files

Repository files navigation