Guide cho người viết workload

Cách viết và duy trì một test repository Playwright mà Orbit chạy được: cấu trúc repo, manifest, tag và owner, lock, cách Orbit lấy danh sách test, variable, secret và test account, và cách check công việc của bạn ở local, trên Station và trong CI.

Trang này dành cho ai

Người viết test Playwright trong một workload repository. Bạn biết Playwright, Git và Node.js. Bạn không cần biết Orbit hoạt động bên trong ra sao.

Trước khi bắt đầu

• Repository nằm trong GitHub organisation dành cho Orbit của tổ chức bạn (trang này viết là <your-org>). Cách bắt đầu nhanh nhất là tạo repository mới từ template orbit-workload-template: template đã có sẵn manifest, Playwright config, fixture, thư mục data và CI check.
• Node.js và Git trên máy của bạn, và quyền đọc <your-org>.
• Từ Project Admin của bạn: team slug cho manifest (ví dụ example-customer-team) và environment mà repository của bạn test (ví dụ dev). Repository được đăng ký trong Console bởi Project Admin hoặc System Admin; xem Onboard project của khách hàng vào Orbit.
• Để chạy test trên Station, bạn cần role QA Engineer (hoặc cao hơn) trong project.

Các bước

1. Sắp xếp repository

orbit.workload.yaml          the manifest (required, in the root, on the default branch)
playwright.config.ts         reads every address from environment variables
package.json
package-lock.json            or pnpm-lock.yaml: exactly one lockfile, matching the manifest
suites/
  AUTO_MM01_ASSIGNMENT_RULE/ one folder per suite
    assignment-rule.spec.ts
  AUTO_MM02_MATERIAL/
    create-material.spec.ts
fixtures/                    test.extend fixtures and page objects
data/                        test data: no addresses, no credentials
.env.example                 variable names only (KEY=), never values
.gitignore                   covers .env*, test-results/, playwright-report/
CODEOWNERS                   optional: test owners per path
.github/workflows/validate.yml   the Orbit check on pull requests

• Một suite là thư mục đầu tiên dưới suites/ chứa file test. Repository không có suites/ thì dùng thư mục cấp cao nhất của mỗi file. Suite quan trọng với run song song, report và lock (bước 6).
• Một repository test một environment. Với environment khác (ví dụ qas), Project Admin đăng ký một repository khác hoặc nhờ bạn tạo.
• Không bao giờ commit file .env. Chỉ được có .env.example, chứa tên và không có giá trị.

2. Viết manifest

Manifest là file orbit.workload.yaml ở thư mục gốc của repository, trên default branch. Một ví dụ đầy đủ:

schemaVersion: 1
id: example-customer-dev          # the workload id: unique across Orbit, cannot change later
name: Example Customer Dev        # display name; you can change it
team: example-customer-team       # the team slug from your Project Admin
runner:
  type: playwright
  config: playwright.config.ts    # default
install:
  packageManager: npm             # npm or pnpm; the matching lockfile must exist
  browsers: [chromium]            # chromium, firefox, webkit
environment:
  slug: dev                       # the environment this repository tests (optional but recommended)
  required: [BASE_URL]            # names of plain variables the tests read
  secrets: [APP_USER, APP_PASS]   # names of secrets the tests read
  dataDir: data                   # optional; checked for addresses and credentials
profiles:
  smoke:
    grep: "@smoke"
    workers: 2
    retries: 1
  regression:
    workers: 4
    retries: 2
    timeoutMinutes: 180
  default: regression             # optional; else the first profile
locks:
  - { tag: "@mutates-config", scope: suite }
artifacts:                        # optional; these are the defaults
  traces: on-failure
  videos: on-failure
  screenshots: on-failure
metadata:
  taxonomy: orbit-v1
  requireTestId: false
  vocabulary:
    module: [mm, sd]
    role: [requestor, approver]

Key	Quy tắc
id	Chữ thường, chữ số và dấu gạch ngang, từ 3 đến 50 ký tự. Nó trở thành tên của workload trong Orbit và không đổi được sau khi đăng ký.
team	Team slug mà Project Admin đưa cho bạn. Orbit từ chối repository có team không có role trong project.
environment.required, environment.secrets	Chỉ tên, không bao giờ có giá trị. Chữ hoa, chữ số và _, bắt đầu bằng một chữ cái. Các tên bắt đầu bằng ORBIT_ đã được dành riêng. Run dừng trước khi bắt đầu nếu một trong các tên này không có giá trị.
environment.slug	Environment duy nhất của project mà repository này test.
profiles	Ít nhất một. Profile là một bộ giá trị mặc định có tên cho run: project (Playwright project), grep và grepInvert, workers (1 đến 16), retries (0 đến 5), timeoutMinutes (1 đến 720, mặc định 120) và headed. default: chỉ định một profile trong số đó.
locks	Tag của các test thay đổi setting dùng chung. Xem bước 6.
metadata.vocabulary	Các giá trị được phép của tag @module:, @feature:, @process:, @scenario: và @role:.
Các key cấp cao nhất khác	Không được phép, trừ các key riêng của bạn bắt đầu bằng x-, Orbit bỏ qua chúng.

Mỗi run đọc manifest của chính commit mà nó chạy. Manifest lỗi trên một branch khiến các run của branch đó fail với “The workload’s manifest has errors”; các branch khác vẫn chạy bình thường.

3. Gắn tag cho test

Tag nằm trong phần details của test. Orbit đọc chúng khi lấy danh sách test.

import { test, expect } from '../../fixtures';

test('creates a material', {
  tag: ['@id:MM-001', '@priority:P1', '@req:MM-123', '@module:mm', '@smoke'],
}, async ({ page }) => {
  // …
});

Tag	Format	Bắt buộc
@priority:P1 … @priority:P4	P1 đến P4 (p1 được chấp nhận và đọc là P1)	Có. Test không có priority sẽ fail check. Priority quyết định quality gate.
@id:<ID>	Chữ hoa và chữ số, chia thành các phần bằng dấu gạch ngang, kết thúc bằng một số: MM-001, BP-CR-001. Duy nhất trong repository, tối đa một tag cho mỗi test.	Cảnh báo khi thiếu; lỗi khi manifest có requireTestId: true.
@req:<KEY>	Một requirement key như ABC-123. Một test có thể có nhiều key.	Không. Tag này liên kết test với một requirement để tính requirement coverage. Key mà project không có sẽ hiện là chưa được cover ở đó; Orbit không từ chối nó.
@module:, @feature:, @process:, @scenario:, @role:	Một giá trị trong metadata.vocabulary	Không. Giá trị nằm ngoài vocabulary là lỗi.
Flag như @smoke	@ và các từ viết thường nối bằng dấu gạch ngang	Không. Dùng chúng trong grep của profile.
Lock tag như @mutates-config	Khai báo dưới locks	Không. Xem bước 6.

Mọi tag phải có dạng @key:value hoặc @flag. Dạng khác đều là lỗi.

4. Đặt owner cho test

Orbit hiển thị owner cho mọi test. Orbit lấy giá trị đầu tiên tìm được theo thứ tự:

1. Annotation orbit.owner của test hoặc của test.describe chứa nó:

   test('creates a material', {
     tag: ['@id:MM-001', '@priority:P1'],
     annotation: { type: 'orbit.owner', description: '@anna.tran' },
   }, async ({ page }) => { /* … */ });

2. Dòng CODEOWNERS ứng với file spec (.github/CODEOWNERS, CODEOWNERS hoặc docs/CODEOWNERS).

3. team trong manifest.

Annotation phải là static, nằm trong phần details của test như trên. Annotation được thêm trong lúc test chạy sẽ không được thấy. Test chỉ có owner là team của manifest được tính là No explicit owner trong test debt của Console. Quy tắc đầy đủ: Onboard project của khách hàng vào Orbit.

5. Giữ config an toàn khi load

Station lấy danh sách test của bạn (cho Explorer, và trước mỗi run) bằng cách load Playwright config. Trong lúc lấy danh sách:

• Chỉ có variable thông thường được đặt. Secret và test account thì không. Không bao giờ đọc secret trong playwright.config.ts, trong global setup chạy lúc load, hoặc ở cấp cao nhất của file spec.
• Đọc secret bên trong test và fixture, nơi chúng đã được đặt.
• Variable bắt buộc bị thiếu trong lúc check sẽ nhận một giá trị placeholder, nên config không được gọi tới hệ thống đang test trong lúc load.
• Annotation và tag phải là static (xem bước 3 và 4).

Nếu config cần một thứ không có sẵn, Station hiển thị “The test list could not be refreshed” với catalog-refresh-failed, kèm lý do.

Một config tuân theo các quy tắc này:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './suites',
  use: { baseURL: process.env.BASE_URL },   // a plain variable: fine at load time
});

6. Dùng lock cho test thay đổi setting dùng chung

Một số test thay đổi configuration mà các test khác phụ thuộc vào. Gắn cho chúng một lock tag và khai báo nó:

locks:
  - { tag: "@mutates-config", scope: suite }

• scope: suite: các run của cùng một suite chờ nhau; các suite khác nhau vẫn chạy cùng lúc.
• scope: environment: khi một run đang giữ lock, không run nào khác trên environment đó chạy các test này.
• Bên trong một suite có test gắn lock tag, các test luôn chạy lần lượt từng test, bất kể số worker.

Xem thêm, kể cả một run đang chờ trông ra sao: Các tính năng run trên Station.

7. Đọc variable, secret và test account trong test

Mọi thứ đến với test của bạn dưới dạng environment variable. Bạn đọc chúng bằng process.env.

Gì	Giá trị đến từ đâu	Cách đọc
Variable thông thường (environment.required)	Console, do Project Admin đặt cho từng environment. Member của project đọc được.	process.env.BASE_URL
Secret (environment.secrets)	Console, write-only. Station chỉ nhận chúng cho run.	process.env.APP_PASS, bên trong test hoặc fixture
Test account	Pool test account của project. Station lease chúng cho một run, nên hai run không bao giờ dùng chung một account.	ORBIT_ACCOUNT_<ROLE>_USERNAME và ORBIT_ACCOUNT_<ROLE>_PASSWORD
Thông tin về run	Do Station đặt	ORBIT_PROJECT, ORBIT_ENVIRONMENT, ORBIT_WORKLOAD, ORBIT_STATION_ID

Về test account:

• Project Admin đặt các role mà workload của bạn cần trên mỗi environment, và số account cho mỗi role (Project settings, Test accounts, Workload needs). Khi không có needs, run dùng secret của environment.
• Role được viết hoa, - đổi thành _: role gl-admin cho ra ORBIT_ACCOUNT_GL_ADMIN_USERNAME. Account thứ hai của một role kết thúc bằng _2, account thứ ba bằng _3.
• Với role chỉ có một account, Project Admin có thể thêm alias, để các test cũ đang đọc, ví dụ, APP_USER và APP_PASS vẫn chạy được.

const role = 'APPROVER';
const user = process.env[`ORBIT_ACCOUNT_${role}_USERNAME`];
const password = process.env[`ORBIT_ACCOUNT_${role}_PASSWORD`];

Orbit ẩn giá trị secret và password được lease trong run log và report. Dù vậy, đừng bao giờ tự in secret ra, và đừng bao giờ đặt địa chỉ hay credential trong data/ hoặc trong code.

8. Chạy test trên máy của bạn

1. Cài dependency: npm ci (hoặc pnpm install --frozen-lockfile), rồi npx playwright install chromium.
2. Đặt các giá trị cần thiết vào file .env ở local. File này nằm trong .gitignore; không bao giờ commit nó. Template load file này bằng process.loadEnvFile('.env') khi chạy local.
3. Chạy Playwright như bình thường, ví dụ npx playwright test --grep @smoke.

Run ở local dùng để viết và debug. Kết quả của chúng không được gửi lên Orbit.

9. Chạy test trên Station

1. Push branch của bạn.
2. Trên Station, mở Run. Chọn environment, workload và profile, rồi gõ branch của bạn vào Branch, tag or commit. Chọn Start run.
3. Explorer hiển thị danh sách test gần nhất mà Station này lấy về. Sau khi merge vào default branch, chọn Refresh from main để thấy các test mới. Xem Các tính năng run trên Station.
4. Đọc kết quả như mọi run khác: trang run, Open report, và run đó trong Console. Guide cho tester mô tả quy trình hằng ngày.

Khi lockfile thay đổi, run đầu tiên trên mỗi Station sẽ cài dependency mới, nên chậm hơn. Nếu lockfile của bạn có thêm package từ một private repository khác, hãy báo Project Admin: workload cần chạy Refresh dependencies một lần trong Console.

10. Check công việc ở local và trong CI

Orbit workload check kiểm tra manifest, tag và các quy tắc của repository. Cài dependency trước, rồi chạy check trong thư mục repository:

npx github:<your-org>/orbit-workload-tools validate
npx github:<your-org>/orbit-workload-tools validate --no-list   # skip the test list (faster)

Check in ra từng finding kèm file và dòng, rồi OK hoặc FAILED cùng số test, profile, lỗi và cảnh báo.

Trong CI, mọi workload repository chạy cùng check này trên pull request, qua reusable workflow của tổ chức bạn (template đã có sẵn trong .github/workflows/validate.yml):

name: Validate
on: [pull_request]
jobs:
  orbit:
    uses: <your-org>/.github/.github/workflows/validate-workload.yml@v1

Trên GitHub, các finding hiện thành annotation trên pull request và trong job summary. Check này thường là bắt buộc trước khi merge vào main.

Những gì check từ chối:

Quy tắc	Lỗi hay cảnh báo
Manifest không khớp schema, hoặc có key cấp cao nhất không xác định	Lỗi
Thiếu lockfile, hoặc có lockfile của package manager khác	Lỗi
runner.config không tồn tại, hoặc playwright test --list fail	Lỗi
Một test không có @priority, có @id sai format, @id bị trùng, hoặc giá trị tag nằm ngoài vocabulary	Lỗi
File .env đã bị commit, hoặc .env.example có giá trị	Lỗi
Một file trong dataDir chứa địa chỉ, key giống credential hoặc giá trị giống secret	Lỗi
Một test không có @id (và requireTestId là false)	Cảnh báo
Một profile không chọn được test nào	Cảnh báo

Những gì có thể sai

Bạn thấy	Lý do	Cần làm gì
priority-missing từ check	Một test không có @priority:P1…P4.	Thêm tag.
id-duplicate	Hai test có cùng @id.	Cho mỗi test một id riêng.
vocabulary	Một giá trị @module: (hoặc tag tương tự) không có trong metadata.vocabulary.	Thêm giá trị vào vocabulary, hoặc sửa tag.
env-file	File .env đã bị commit, hoặc .env.example có giá trị.	Gỡ file khỏi Git; chỉ giữ tên trong .env.example.
playwright-list	Playwright không lấy được danh sách test, thường vì chưa cài dependency.	Chạy npm ci (hoặc pnpm install --frozen-lockfile) rồi thử lại.
“The test list could not be refreshed” (catalog-refresh-failed) trên Station	Config không load được khi chỉ có variable thông thường, ví dụ vì nó đọc một secret.	Chuyển việc đọc secret vào test hoặc fixture (bước 5).
“Variables are missing” trên một run	Một tên trong environment.required hoặc environment.secrets không có giá trị cho environment đó.	Nhờ Project Admin đặt giá trị trong Console.
“The workload’s manifest has errors” trên một run	Manifest của branch đó không hợp lệ.	Chạy check trên branch đó và sửa.
Console từ chối đăng ký repository	Sai team, id đã được dùng, hoặc không có manifest trên default branch.	Xem Onboard project của khách hàng vào Orbit.
Test hiện No explicit owner	Không có annotation orbit.owner và không có dòng CODEOWNERS.	Thêm một trong hai (bước 4).
Hai run cùng thay đổi một setting và làm hỏng nhau	Các test không có lock tag.	Thêm lock (bước 6).

Các giá trị cần ghi lại

Giá trị	Tìm ở đâu	Loại
Repository <your-org>/<repo>	GitHub	Không phải secret
id của workload	Manifest	Không phải secret; không đổi được sau khi đăng ký
Team slug	Từ Project Admin; team trong manifest	Không phải secret
Environment slug	Từ Project Admin; environment.slug trong manifest	Không phải secret
Tên variable và secret	environment.required và environment.secrets trong manifest	Tên không phải secret. Giá trị chỉ được giữ trong Console, không bao giờ trong repository.
Role của test account	Từ Project Admin (Workload needs)	Không phải secret

Các guide liên quan

• Các tính năng run trên Station: run option, run song song, time limit và lock.
• Onboard project của khách hàng vào Orbit: cách Project Admin đăng ký repository của bạn và đặt các giá trị cho nó.
• Guide cho tester: chạy test và đọc kết quả trên Station.
• Bắt đầu với Orbit: tóm tắt về Console và Station.
• FAQ.