AUTOMATION QA GUIDELINES

Project: Stack Trading
Date created: 2026-07-21
Version: v1.0
Owner: AQA
Language: Vietnamese / English

Tài liệu duy nhất cho Automation QA (AQA): phạm vi, setup framework, coding standards, thiết kế test và CI/CD reporting.

Mục lục

I. Overview

I.1. Mục tiêu

Automation QA đảm bảo:

• Các luồng nghiệp vụ quan trọng (checkout, evaluation, KYC, trading dashboard, payout…) được kiểm thử lặp lại ổn định trên môi trường test.
• Regression chạy nhanh sau mỗi build / sprint mà không phụ thuộc hoàn toàn vào manual QC.
• Framework, test data và report tách biệt khỏi dữ liệu nhạy cảm của dự án khác — chỉ dùng data/fixture thuộc Stack Trading (hoặc demo public khi POC).

I.2. Phạm vi

I.3. Vai trò & trách nhiệm

I.4. Tech stack chuẩn

I.5. Luồng làm việc AQA

BA SRS / QC test case
        │
        ▼
AQA viết Feature (Gherkin) ──► Review với QC (coverage)
        │
        ▼
Implement steps + page objects + testData
        │
        ▼
Chạy local (npm run test:chromium)
        │
        ▼
Merge PR ──► CI chạy automation ──► Report HTML / JUnit
        │
        ▼
Fail → bug ticket / flaky triage

I.6. Nguyên tắc bắt buộc

1. Không commit credentials thật, token, webhook, PII của trader/customer.
2. Test data chỉ lấy từ testData/ của repo automation hoặc env CI secrets.
3. Mỗi scenario phải độc lập (không phụ thuộc thứ tự chạy).
4. Prefer data-test / role / label ổn định — tránh XPath phụ thuộc CSS layout.
5. Fail phải có screenshot + log step rõ ràng để QC/Dev triage nhanh.

I.7. Liên kết liên quan

• BA Common Rules: Quy Tắc Nghiệp Vụ Chung
• Project context: project_context.md (repo BA-QC)
• Automation repo: https://github.com/sotatek-dev/StackTrading-automation-test

II. Framework Setup

II.1. Prerequisites

Network access tới môi trường test Stack Trading (hoặc https://www.saucedemo.com/ khi chạy POC demo).

II.2. Clone & install

git clone git@github.com:sotatek-dev/StackTrading-automation-test.git
cd StackTrading-automation-test
npm install
npm run install:browsers

Hoặc one-shot:

npm run setup

(setup = install deps + husky + Playwright browsers + lint/review checks)

II.3. Cấu hình môi trường

Ví dụ:

BASE_URL="https://staging.stacktrading.example/" npm run test:chromium

Test data tĩnh:

testData/
  testSite.json    # baseUrl fallback
  users.json       # demo / test accounts (không chứa secret production)
  messages.json    # expected UI text

II.4. Chạy test

# Chromium (recommended default)
npm run test:chromium

# Firefox / WebKit
npm run test:firefox
npm run test:webkit

# All browsers
npm run test:all-browsers

Chạy trực tiếp Cucumber (debug):

BASE_URL="https://www.saucedemo.com/" BROWSER="chromium" \
  npx cucumber-js --require-module ts-node/register \
  --config config/cucumber.config.ts --profile chromium

II.5. Cấu trúc thư mục framework

StackTrading-automation-test/
├── features/                 # Gherkin *.feature
│   └── SauceDemo/
├── stepDefinitions/          # Cucumber steps (*.steps.ts)
├── pageObjects/              # Page Object classes (optional)
├── testData/                 # JSON fixtures
├── hooks/                    # Before/After + performance hooks
├── support/                  # World, globalSetup/Teardown
├── config/
│   ├── playwright.config.ts
│   ├── cucumber.config.ts
│   └── report/               # HTML reporter
├── performance/e2e/          # Web Vitals capture (optional)
├── reports/                  # Generated (gitignored)
└── package.json

II.6. Reports sau khi chạy

npm run report:open

reports/ và test-results/ không commit (đã có trong .gitignore).

II.7. Troubleshooting nhanh

III. Coding Standards

Áp dụng cho mọi PR trong repo StackTrading-automation-test.

III.1. Naming

III.2. Gherkin style

• Dùng Given / When / Then rõ ràng; Background chỉ cho setup chung thật sự.
• Tránh bước “And I wait 5 seconds” — chờ bằng assertion / Playwright auto-wait.
• Data biến động đưa vào {string} hoặc Examples (Scenario Outline).
• Không hardcode URL môi trường trong feature — lấy từ config / testData.

Good:

Given I open the SauceDemo login page
When I login with username "standard_user" and password "secret_sauce"
Then I should be logged in and see the Products page

Avoid:

When I click the third blue button on the left
And I sleep for 10 seconds

III.3. Step definitions

• Một domain ≈ một file steps (không gom “god file”).
• Steps gọi Page Object hoặc locator tập trung; tránh copy-paste selector.
• Log action/verify qua lib/log (logAction, logVerify, logInfo).
• Không console.log raw secrets (password → mask ************).

When('I login with username {string} and password {string}', async function (username, password) {
  await this.page.locator('#user-name').fill(username);
  await this.page.locator('#password').fill(password);
  await this.page.locator('#login-button').click();
});

III.4. Selectors (ưu tiên)

Tránh selector phụ thuộc index (nth-child(3)), class hash CSS-in-JS, text i18n chưa ổn định.

III.5. Test data

• Mọi account / message / URL fallback nằm trong testData/*.json.
• Load qua dataHelper.loadTestData('users.json').
• Cấm commit: production password, OTP seed, Slack token, API key.
• Demo public (vd. SauceDemo secret_sauce) được phép ghi rõ trong docs/feature.

III.6. Hooks & World

• hooks/hooks.ts: init browser, screenshot on fail, cleanup.
• support/world.ts: chỉ giữ state dùng chung (page, config); không nhồi business logic.
• Timeout step mặc định đủ lớn cho E2E; không tăng vô hạn để che flake.

III.7. PR checklist (AQA)

• Feature + steps + data nằm đúng folder
• Scenario độc lập, có tag @smoke nếu thuộc critical path
• Không commit reports/, node_modules/, secrets
• Chạy pass local trên Chromium trước khi request review
• Selector ưu tiên data-test / role
• Fail path có assertion message rõ

IV. Test Design

IV.1. Nguồn đầu vào

Mỗi automated scenario nên map được tới UC-ID hoặc QC case ID (ghi trong comment Feature hoặc tag).

IV.2. Mức độ ưu tiên automate

Không automate trước: exploratory one-off, bug chưa ổn định UI, flow phụ thuộc CAPTCHA/OTP thật chưa có test hook.

IV.3. Tags chuẩn

Ví dụ:

@smoke @login
Feature: Authentication smoke

CI default nên chạy: @smoke hoặc full suite trừ @wip.

IV.4. Cấu trúc scenario tốt

1. Arrange — mở page / login (Background nếu dùng lại nhiều lần).
2. Act — một hành động chính rõ ràng.
3. Assert — 1–3 verification đủ để chứng minh pass/fail.

Tránh scenario “siêu dài” trừ khi đó là journey test có chủ đích và tag riêng (@e2e-journey).

IV.5. Positive vs negative

IV.6. Data strategy

IV.7. Traceability matrix (mẫu)

IV.8. Definition of Done (scenario)

• Feature + steps + data merged
• Pass ổn định ≥ 3 lần local / CI
• Có tag priority phù hợp
• Map UC/QC ID
• Screenshot on fail hoạt động
• Manual QC confirm coverage đủ cho case đã chọn

V. CI/CD & Reporting

V.1. Mục tiêu CI

• Chạy smoke trên mỗi PR (nhanh, ổn định).
• Chạy regression theo lịch (nightly / end of sprint).
• Xuất artifact HTML + JUnit để QC/Dev xem mà không cần máy local.

V.2. Pipeline đề xuất

checkout → npm ci → playwright install →
  cucumber (chromium, tags=@smoke) →
  report:html → upload artifacts (reports/)

Env trên CI:

env:
  CI: "true"
  BASE_URL: ${{ secrets.STAGING_BASE_URL }}
  # credentials qua secrets, không hardcode

V.3. Scripts liên quan (repo automation)

V.4. Artifacts cần upload

Không upload node_modules hay binary app nội bộ.

V.5. Đọc report

1. Mở HTML report → Features / Scenarios.
2. Scenario FAILED → xem step đỏ + screenshot đính kèm.
3. Phân loại:
   • Product bug → ticket Dev, gắn UC/CR
   • Test bug (selector/data) → AQA fix PR
   • Env / flake → retry + quarantine @wip nếu tái diễn

V.6. Flaky test policy

Nguyên tắc: sửa gốc (wait đúng, selector ổn) trước khi tăng retry vô hạn.

Retry Cucumber trên CI (khi CI=true) chỉ là lớp an toàn tạm thời.

V.7. Quality gates (đề xuất)

V.8. Bảo mật trên CI

• Secrets chỉ qua GitHub Actions / CI vault.
• Log không in password / token.
• BASE_URL staging — không trỏ production trừ khi có approval riêng.