@xylentis/testgen 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.2.0 (2026-10-06)
+
+- **Sửa bước trong giao diện:** sửa locator (viết như trong test Playwright, ví dụ `getByRole('button', { name: 'Đăng nhập' })`), chữ đã gõ, giá trị đã chọn, giá trị assert, phím, đường dẫn file upload; đổi thứ tự hoặc xóa bước; **Undo** để quay lại. testgen chặn những thay đổi làm một trang bị dùng trước khi mở hoặc sau khi đóng.
+- **Replay:** chạy lại các bước bằng Playwright ngay trong giao diện, mỗi bước hiện ✓ hoặc ✗. Bước lỗi có thông báo, ảnh chụp trang lúc lỗi và nút **Edit** để sửa. Replay chạy chính bản ghi trên Playwright, không chạy code Selenium đã sinh.
+- **Checks:** testgen nhắc những chỗ nên xem lại trước khi dùng test: không có assertion nào, các bước cuối không được kiểm tra, locator dựa vào vị trí (`nth`, `first`) hay cấu trúc trang (XPath, `div > span`), file upload chỉ có tên, locator dựa vào chữ hiển thị khi app chưa có test id, và các `// TODO(testgen)` của từng target. Giao diện hiện trong mục **Checks**, CLI in ra sau khi sinh code.
+- **Mật khẩu không còn nằm trong test.** Giá trị gõ vào ô mật khẩu, PIN, OTP, token, API key… được đọc từ biến môi trường, ví dụ `TEST_PASSWORD`: Java `TestgenSupport.secret("TEST_PASSWORD")`, TypeScript/JavaScript `secret('TEST_PASSWORD')`, Go `os.LookupEnv("TEST_PASSWORD")`. Thiếu biến thì test dừng ngay với thông báo rõ ràng. Giá trị đó cũng không vào file CSV, bản ghi do `testgen record` lưu và file của **Download recording**. Khi giá trị nằm trong một chữ khác (locator, chữ mong đợi), code dùng `secret(...)` ở đúng chỗ đó và bản ghi lưu `${TEST_PASSWORD}`. Log và thông báo lỗi của Selenium và của Replay hiện `***`. Trong giao diện có thể bật/tắt và đặt tên biến cho từng bước; bước đã là secret vẫn là secret khi sửa locator.
+  - Đây là thay đổi so với 1.1.x: test sinh từ bản ghi có ô mật khẩu cần đặt biến môi trường trước khi chạy, ví dụ `TEST_PASSWORD=... mvn test`.
+- **Data-driven cho mọi target:** `playwright-ts`, `playwright-go` và `selenium-js` cũng đọc dữ liệu từ CSV và chạy test một lần cho mỗi dòng. File CSV nằm cạnh file test, riêng Go nằm trong `testdata/`. Chữ trong locator *chứa* giá trị đã gõ nay cũng đi theo dữ liệu, ví dụ `filterHasText(whatNeedsToBeDone + " Delete")` thay cho `filterHasText("Buy milk Delete")`.
+- **Bảo mật giao diện:** server của `testgen ui` chỉ nhận thay đổi từ chính trang testgen (kiểm tra `Origin`, `Sec-Fetch-Site` và yêu cầu JSON). Trước đây một trang web khác đang mở trong trình duyệt có thể gửi lệnh tới `testgen ui`, ví dụ ghi file vào thư mục project.
+- **`--log-steps` cho `selenium-js`:** test gọi `page.setLogger(console.log)`, ghi từng bước và kết quả từng assert như bản Java. Hai target Playwright không cần tùy chọn này vì report và trace của Playwright đã có từng bước.
+- Tài liệu hướng dẫn sử dụng chi tiết: [docs/huong-dan-su-dung.md](https://git.xylentis.com/tools/automation-test-code/-/blob/main/docs/huong-dan-su-dung.md).
+
+## 1.1.2 (2026-10-06)
+
+- Thêm target `selenium-java-testng`: Selenium WebDriver + TestNG (`@BeforeMethod`, `@AfterMethod(alwaysRun = true)`, `@Test`), dùng chung `TestgenSupport.java` với `selenium-java`. Project mẫu ở `e2e/projects/selenium-java-testng`.
+- Thêm `--log-steps` (ô **Log steps** trong giao diện): test Java ghi log từng bước kèm giá trị và kết quả từng assert (`passed` / `FAILED`). TestNG ghi qua `Reporter.log`, JUnit in ra console. Trong log và thông báo lỗi, các trang mở sau (popup) được gọi là `page1`, `page2`…, đúng tên biến trong test.
+- Thêm `--data-driven` (ô **Data-driven (CSV)**): giá trị đã gõ, chọn và assert thành cột của `<Tên>Test.csv`, đặt trong `src/test/resources/<package>/`. Test chạy một lần cho mỗi dòng, qua `@DataProvider` (TestNG) hoặc `@ParameterizedTest` (JUnit). File CSV đã có không bao giờ bị ghi đè.
+- `TestgenSupport.readCsv(...)` đọc CSV UTF-8 có hoặc không có BOM, phân cách bằng dấu phẩy hoặc chấm phẩy.
+- `testgen targets` căn cột theo id dài nhất.
+
+## 1.1.1 (2026-10-06)
+
+- Code sinh ra luôn dùng thuộc tính test id mà bản ghi đã dùng. Trước đây, đổi **Test id attribute** trong giao diện sau khi ghi, hoặc truyền `--test-id-attribute` khác cho `testgen generate`, làm `getByTestId(...)` tìm theo sai thuộc tính. Nay giao diện hiện ghi chú khi ô này khác với bản ghi, còn `testgen generate` báo khi bỏ qua tùy chọn.
+- README: thêm mục về cách recorder chọn locator và cách xử lý web nhiều ngôn ngữ (i18n).
+
 ## 1.1.0 (2026-10-06)
 
 - Khi ghi thao tác không còn mở cửa sổ Playwright Inspector, chỉ còn trình duyệt bạn đang thao tác. Code xem trong giao diện testgen hoặc trong các file sinh ra.

package/README.md

@@ -2,6 +2,9 @@
 
 Ghi thao tác trên web **một lần** bằng recorder của Playwright, rồi sinh test UI cho **nhiều framework và nhiều ngôn ngữ**.
 Cách dùng giống `npx playwright codegen`, nhưng không chỉ sinh code Playwright mà còn sinh cả Selenium, và thêm ngôn ngữ Go.
+Trong giao diện, bạn sửa được từng bước, chạy thử lại (Replay) và xem các cảnh báo trước khi lưu test: **ghi → sửa → chạy thử → xuất**.
+
+Hướng dẫn từng bước, có ví dụ cho từng target: **[Hướng dẫn sử dụng](https://git.xylentis.com/tools/automation-test-code/-/blob/main/docs/huong-dan-su-dung.md)** (`docs/huong-dan-su-dung.md`).
 
 ![Giao diện testgen](https://cdn.jsdelivr.net/npm/@xylentis/testgen@1/docs/testgen-ui.png)
 
@@ -10,6 +13,7 @@ Cách dùng giống `npx playwright codegen`, nhưng không chỉ sinh code Play
 | `playwright-ts` | Playwright Test (`@playwright/test`) | TypeScript | `login.spec.ts` |
 | `playwright-go` | [playwright-go](https://github.com/mxschmitt/playwright-go) + testify | Go | `login_test.go` |
 | `selenium-java` | Selenium 4 + JUnit 5 | Java 17+ | `LoginTest.java` + `TestgenSupport.java` |
+| `selenium-java-testng` | Selenium 4 + TestNG | Java 17+ | `LoginTest.java` + `TestgenSupport.java` |
 | `selenium-js` | Selenium 4 + Mocha | JavaScript | `login.spec.js` + `testgen-support.js` |
 
 ## Cài đặt
@@ -40,16 +44,30 @@ testgen ui                  # mở http://127.0.0.1:9323
 2. Một cửa sổ trình duyệt mở ra. Bạn thao tác như người dùng thật: click, gõ, chọn…
    - Thanh công cụ của recorder nằm ở đầu trang, dùng để thêm assert: *Assert visibility*, *Assert text*, *Assert value*.
    - Cửa sổ Playwright Inspector được ẩn đi, chỉ còn trình duyệt bạn đang thao tác. Muốn hiện lại thì dùng `testgen record --inspector`.
-3. Trong khi bạn thao tác, giao diện testgen cập nhật **danh sách bước** và **code của cả 4 target**.
+3. Trong khi bạn thao tác, giao diện testgen cập nhật **danh sách bước** và **code của mọi target**.
 4. Đóng trình duyệt hoặc bấm **Stop** khi xong.
-5. Với từng target, bạn có thể **Copy**, **Download** hoặc **Save files** để lưu thẳng vào thư mục project. Đường dẫn tính từ thư mục bạn chạy `testgen ui`.
+5. Sửa các bước nếu cần, bấm **Replay** để chạy thử, rồi xem mục **Checks** (xem bên dưới).
+6. Với từng target, bạn có thể **Copy**, **Download** hoặc **Save files** để lưu thẳng vào thư mục project. Đường dẫn tính từ thư mục bạn chạy `testgen ui`.
 
 Một số thao tác khác:
 
-- **Đổi Test name / Package / Test id attribute:** code sinh lại ngay.
-- **Download recording:** lưu file `.jsonl` để lần sau sinh lại.
+- **Đổi Test name / Package:** code sinh lại ngay.
+- **Test id attribute:** đặt trước khi bấm **Record**. Code luôn dùng thuộc tính mà bản ghi đã dùng, nên đổi sau khi ghi chỉ có tác dụng cho lần ghi sau. Giao diện hiện ghi chú khi hai giá trị khác nhau. Xem thêm mục **Locator và web nhiều ngôn ngữ** bên dưới.
+- **Log steps** (target Selenium) và **Data-driven (CSV)** (mọi target): xem mục **Log từng bước và test data-driven** bên dưới.
+- **Download recording:** lưu file `.jsonl` để lần sau sinh lại. File không chứa mật khẩu đã gõ, xem mục **Mật khẩu và dữ liệu nhạy cảm**.
 - **Open recording…:** mở lại một file đã lưu.
 
+### Sửa bước, Replay và Checks
+
+- **Sửa bước:** rê chuột (hoặc Tab) vào một bước để hiện **Edit**, **↑**, **↓**, **✕**. **Edit** cho sửa:
+  - locator, viết như trong test Playwright: `getByRole('button', { name: 'Đăng nhập' })`, `getByLabel('Email')`, `getByTestId('save')`, `locator('#email')`;
+  - chữ đã gõ, giá trị đã chọn, chữ hoặc giá trị mong đợi của assert, phím (`Enter`, `Shift+Tab`), URL, đường dẫn file upload;
+  - ô **Secret** của bước gõ chữ: giá trị đọc từ biến môi trường nào.
+
+  **↑ ↓** đổi thứ tự, **✕** xóa, **Undo** quay lại thay đổi trước. testgen chặn những thay đổi làm một trang bị dùng trước khi mở hoặc sau khi đóng, ví dụ xóa bước mở popup khi các bước sau vẫn thao tác trên popup đó.
+- **Replay:** chạy lại các bước bằng Playwright, trong trình duyệt của bản ghi. Mỗi bước hiện ✓ hoặc ✗. Bước lỗi hiện thông báo và ảnh chụp trang lúc lỗi; bấm **Edit step N** để sửa rồi Replay lại. Replay chạy chính bản ghi, nên nó cho biết locator và dữ liệu còn đúng trên Playwright, **chưa** cho biết code Selenium có chạy được hay không (xem **Giới hạn hiện tại**).
+- **Checks:** những chỗ nên xem lại trước khi dùng test, ví dụ bản ghi không có assertion nào, các bước cuối không được kiểm tra, locator dựa vào vị trí (`nth(1)`) hay cấu trúc trang (XPath), file upload chỉ có tên, và những gì target đang xem không làm được (`// TODO(testgen)`). Bấm vào một dòng để nhảy tới bước đó. Lệnh `testgen record` và `testgen generate` in các cảnh báo này ra sau khi sinh code.
+
 ## Dùng dòng lệnh
 
 ```bash
@@ -64,6 +82,14 @@ testgen generate generated/recording.jsonl -t selenium-java -o src/test/java/com
 testgen generate generated/recording.jsonl -t playwright-go -o e2e/login_test.go
 testgen generate generated/recording.jsonl -d out          # tất cả target, mỗi target một thư mục
 
+# TestNG, log từng bước, dữ liệu đọc từ src/test/resources/com/acme/e2e/SearchTest.csv
+testgen generate generated/recording.jsonl -t selenium-java-testng --log-steps --data-driven \
+  -o src/test/java/com/acme/e2e/SearchTest.java
+
+# Playwright, dữ liệu đọc từ tests/search.csv; Go đọc từ e2e/testdata/search.csv
+testgen generate generated/recording.jsonl -t playwright-ts --data-driven -o tests/search.spec.ts
+testgen generate generated/recording.jsonl -t playwright-go --data-driven -o e2e/search_test.go
+
 testgen targets                                            # liệt kê target
 ```
 
@@ -74,11 +100,64 @@ testgen targets                                            # liệt kê target
 | `-d, --out-dir` | Thư mục ra. Nếu có nhiều target thì mỗi target một thư mục con. |
 | `-n, --name` | Tên test. Mặc định lấy từ tên file `--output`, nếu không có thì là `recorded`. |
 | `--package` | Package cho Java/Go. Java tự lấy từ đường dẫn sau `src/test/java/`, Go tự lấy từ tên thư mục. |
-| `--test-id-attribute` | Thuộc tính dùng cho `getByTestId` (mặc định `data-testid`). |
-| `--save` | (`record`) Nơi lưu bản ghi `.jsonl`. |
+| `--test-id-attribute` | Thuộc tính recorder dùng cho `getByTestId` (mặc định `data-testid`). Khi sinh code, testgen dùng thuộc tính đã lưu trong bản ghi; tùy chọn này chỉ có tác dụng với bản ghi không có bước `getByTestId` nào. |
+| `--log-steps` | (Selenium) Ghi log từng bước và kết quả từng assert khi test chạy. |
+| `--data-driven` | Giá trị đã gõ, chọn và assert thành cột của một file CSV, test chạy một lần cho mỗi dòng. File CSV đã có không bị ghi đè. |
+| `--save` | (`record`) Nơi lưu bản ghi `.jsonl`, không kèm mật khẩu đã gõ. |
 | `--browser`, `--channel`, `--device`, `--viewport-size`, `--lang`, `--timezone`, `--color-scheme`, `--user-agent`, `--ignore-https-errors`, `--load-storage`, `--save-storage` | (`record`) Giống hệt `playwright codegen`. |
 | `--inspector` | (`record`) Hiện thêm cửa sổ Playwright Inspector (mặc định ẩn). |
 
+## Locator và web nhiều ngôn ngữ (i18n)
+
+testgen giữ nguyên locator mà recorder của Playwright chọn. Recorder ưu tiên theo thứ tự:
+
+1. test id: `getByTestId('welcome')`, theo thuộc tính `data-testid` hoặc thuộc tính đặt bằng `--test-id-attribute`;
+2. role + tên (accessible name, thường là chữ hiển thị): `getByRole('button', { name: 'Sign in' })`;
+3. placeholder, label, alt, text, title;
+4. `#id`; sau đó mới đến tên thẻ và vị trí.
+
+`#id` xếp sau vì id thường do framework sinh ra và đổi giữa các lần build (`:r1:` của React, `mat-input-0` của Angular Material). Id trông như chuỗi ngẫu nhiên thì recorder bỏ qua hẳn. Ví dụ trong app demo, `<input id="email">` có label "Email" nên thành `getByRole('textbox', { name: 'Email' })` chứ không phải `#email`.
+
+Vì vậy, nếu app không có test id, phần lớn locator dựa vào chữ trên trang. Test ghi trên giao diện tiếng Anh sẽ gãy khi chạy trên giao diện tiếng Việt: `getByRole('button', { name: 'Sign in' })` không khớp với nút "Đăng nhập". Có ba cách xử lý:
+
+- **Cố định ngôn ngữ khi chạy test.** Ghi với `--lang`, code sinh ra sẽ đặt cùng locale (Selenium: thêm `--lang` cho Chrome và Edge):
+
+  ```bash
+  testgen record https://your-app.example --lang en-US
+  ```
+
+  Cách này chỉ có tác dụng khi app chọn ngôn ngữ theo trình duyệt. Nếu app chọn theo URL (`/en/...`), cookie hay cài đặt tài khoản thì cần cố định ngôn ngữ ở đó, ví dụ ghi từ URL `/en/...` hoặc dùng tài khoản test có ngôn ngữ cố định.
+
+- **Thêm test id vào app.** Đây là cách bền nhất khi một test phải chạy trên nhiều ngôn ngữ, vì test id luôn được ưu tiên. App dùng thuộc tính khác thì khai báo khi ghi, ví dụ `--test-id-attribute data-qa`.
+
+- **Dùng `id` sẵn có làm test id:** `--test-id-attribute id`, hoặc nhập `id` vào ô **Test id attribute** trong giao diện. Phần tử có id thành `getByTestId('email')`, phần tử không có id vẫn dùng role + tên. Chỉ nên dùng khi id do người viết đặt, vì với test id recorder không lọc các id sinh tự động.
+
+Thuộc tính test id được lưu trong bản ghi, và code sinh ra luôn dùng đúng thuộc tính đó. Vì vậy hãy chọn thuộc tính **trước khi ghi**. `--test-id-attribute` khi chạy `generate` chỉ có tác dụng với bản ghi không có bước `getByTestId` nào.
+
+## Mật khẩu và dữ liệu nhạy cảm
+
+Recorder của Playwright ghi lại mọi thứ bạn gõ, kể cả mật khẩu. testgen không để giá trị đó vào test:
+
+- **Phát hiện:** bước gõ chữ vào ô mà locator gọi là mật khẩu, PIN, OTP, mã xác thực, token, API key… (tiếng Anh, tiếng Việt và vài ngôn ngữ khác, ví dụ `getByRole('textbox', { name: 'Mật khẩu' })`, `#txtPwd`, `input[type="password"]`) là bước **secret**.
+- **Code sinh ra đọc biến môi trường** đặt tên theo ô đó: `TEST_PASSWORD`, `TEST_MAT_KHAU`, `TEST_OLD_PASSWORD`… Gõ cùng một giá trị hai lần (mật khẩu và xác nhận mật khẩu) thì dùng chung một biến. Assert kiểm tra đúng giá trị đó cũng đọc biến này.
+
+  ```java
+  page.getByRole("textbox", "Password").fill(TestgenSupport.secret("TEST_PASSWORD"));   // Java
+  ```
+  ```ts
+  await page.getByRole('textbox', { name: 'Password' }).fill(secret('TEST_PASSWORD'));  // TypeScript, JavaScript
+  ```
+  ```go
+  testPassword, ok := os.LookupEnv("TEST_PASSWORD")                                     // Go
+  require.True(t, ok, "set the environment variable TEST_PASSWORD, ...")
+  ```
+
+  Thiếu biến thì test dừng ngay ở đầu với thông báo nêu tên biến. Java đọc cả system property, nên `mvn test -DTEST_PASSWORD=...` cũng được.
+- **Không lưu giá trị:** bản ghi do `testgen record` lưu và file của **Download recording** thay giá trị bằng `""` và ghi tên biến vào bước (`"secret": "TEST_PASSWORD"`). Sinh lại từ file này cho đúng code cũ. Replay một bản ghi như vậy thì giao diện hỏi giá trị và chỉ giữ trong bộ nhớ của `testgen ui`. `testgen generate` nhắc khi file bản ghi cũ vẫn còn giá trị.
+- **Secret nằm trong chữ khác** (ví dụ assert trên phần tử hiện đúng mật khẩu, hay chữ mong đợi `Saved for hunter2!`): code dùng `secret(...)` ở đúng chỗ đó, ví dụ `page.getByText(secret('TEST_PASSWORD'))`, còn bản ghi lưu `${TEST_PASSWORD}` thay cho giá trị.
+- **Log:** `--log-steps`, thông báo lỗi của Selenium và của Replay hiện giá trị secret là `***`.
+- **Sửa khi phát hiện sai:** trong giao diện, **Edit** một bước gõ chữ rồi bật/tắt ô **Secret** hoặc đổi tên biến. Bước đã là secret vẫn là secret khi bạn sửa locator của nó. Với CLI, thêm `"secret": false` (không phải secret) hoặc `"secret": "TEN_BIEN"` vào dòng của bước đó trong file `.jsonl`.
+
 ## Chạy test đã sinh
 
 Trong `e2e/projects/` có sẵn project mẫu cho từng target. Đó là đúng các project dùng để kiểm thử testgen, nên copy về dùng ngay được.
@@ -100,6 +179,8 @@ go test ./...                 # HEADED=1 go test ./... để xem trình duyệt
 
 **selenium-java**: cần `selenium-java` và `junit-jupiter` (xem `e2e/projects/selenium-java/pom.xml`). `LoginTest.java` và `TestgenSupport.java` phải nằm cùng package. Chạy bằng `mvn test`.
 
+**selenium-java-testng**: giống `selenium-java` nhưng chạy bằng TestNG (`@BeforeMethod`, `@AfterMethod`, `@Test`), cần `selenium-java` và `testng` (xem `e2e/projects/selenium-java-testng/pom.xml`). `TestgenSupport.java` giống hệt bản JUnit. Assert sai ném `AssertionError`, nên TestNG báo test đó là Fail. Chạy bằng `mvn test`.
+
 **selenium-js**: cần `selenium-webdriver` và `mocha` (xem `e2e/projects/selenium-js`). `testgen-support.js` phải nằm cạnh file test. Chạy bằng `npx mocha`.
 
 Biến môi trường mà test Selenium hiểu:
@@ -108,6 +189,8 @@ Biến môi trường mà test Selenium hiểu:
 - `SELENIUM_REMOTE_URL=http://grid:4444`: chạy trên Selenium Grid.
 - `TESTGEN_TIMEOUT=15000`: thời gian tự chờ, đơn vị ms, mặc định 10000.
 
+Test của mọi target còn cần các biến secret của nó, ví dụ `TEST_PASSWORD=... npx playwright test` (xem mục **Mật khẩu và dữ liệu nhạy cảm**).
+
 ### Code Selenium trông như thế nào
 
 Selenium không có `getByRole` hay `getByText`, cũng không tự chờ element. Vì vậy test Selenium đi kèm một **file hỗ trợ** (`TestgenSupport.java` / `testgen-support.js`) để code sinh ra vẫn gọn và chạy ổn định:
@@ -126,6 +209,64 @@ Bản JavaScript dùng **đúng API của Playwright** (`page.getByRole('button'
 
 Bên dưới vẫn là Selenium WebDriver: các hành động dùng `WebElement.click()`, `sendKeys()`, `Select`, `Actions`. Biến `driver` vẫn có sẵn trong test nếu bạn cần viết thêm code Selenium thuần.
 
+### Log từng bước và test data-driven
+
+Hai tùy chọn này tương ứng với ô **Log steps** và **Data-driven (CSV)** trong giao diện.
+
+**`--log-steps`** (`selenium-java`, `selenium-java-testng`, `selenium-js`): test gọi `page.setLogger(...)`. Mỗi hành động được ghi kèm giá trị thật (secret hiện `***`), mỗi assert ghi `passed` hoặc `FAILED`. Bản TestNG ghi qua `Reporter.log` (vào report của TestNG và ra console), bản JUnit và bản JavaScript in ra console. Hai target Playwright không cần tùy chọn này: report và trace của Playwright đã có từng bước.
+
+```
+02:51:07.955 page.getByRole("textbox", "Email").fill("dev@example.com")
+02:51:08.121 page.getByTestId("welcome").shouldContainText("Welcome, dev@example.com (vn)") passed
+02:51:28.390 page.getByTestId("welcome").shouldContainText("Welcome, wrong (vn)") FAILED, received: Welcome, dev@example.com (vn)
+```
+
+**`--data-driven`** (mọi target): giá trị đã gõ (`fill`), đã chọn (`selectOption`) và đã assert (`shouldHaveText`, `shouldContainText`, `shouldHaveValue`) trở thành cột của một file CSV. Test chạy một lần cho mỗi dòng, và mỗi dòng có kết quả Pass/Fail riêng. Giá trị secret không thành cột: chúng vẫn đọc từ biến môi trường.
+
+```java
+@DataProvider(name = "loginData")
+public static Object[][] loginData() {
+    return TestgenSupport.readCsv(LoginTest.class, "LoginTest.csv", "email", "password", "expectedWelcome");
+}
+
+@Test(dataProvider = "loginData")
+public void login(String email, String password, String expectedWelcome) {
+    page.getByRole("textbox", "Email").fill(email);
+    page.getByRole("textbox", "Password").fill(password);
+    page.getByRole("button", "Sign in").click();
+    page.getByTestId("welcome").shouldContainText(expectedWelcome);
+}
+```
+
+Bản TypeScript, JavaScript và Go đọc từng dòng thành `row`:
+
+```ts
+const rows = readCsv(path.join(__dirname, 'login.csv'), ['email', 'expectedWelcome']);
+
+for (const [index, row] of rows.entries()) {
+  test(`login (row ${index + 1})`, async ({ page }) => {
+    await page.getByRole('textbox', { name: 'Email' }).fill(row.email);
+    await page.getByRole('textbox', { name: 'Password' }).fill(secret('TEST_PASSWORD'));
+    await page.getByRole('button', { name: 'Sign in' }).click();
+    await expect(page.getByTestId('welcome')).toContainText(row.expectedWelcome);
+  });
+}
+```
+
+| Target | File CSV | Mỗi dòng chạy thành |
+| --- | --- | --- |
+| `selenium-java`, `selenium-java-testng` | `<Tên>Test.csv`, resource cùng package với class test. Khi file test nằm trong `src/test/java/<package>/`, testgen ghi CSV vào `src/test/resources/<package>/`. | một lần chạy của `@ParameterizedTest` (JUnit) hoặc `@Test(dataProvider = ...)` (TestNG) |
+| `playwright-ts` | `<tên>.csv` cạnh file `.spec.ts`, kèm file hỗ trợ `testgen-data.ts` | một test `<tên> (row N)` |
+| `selenium-js` | `<tên>.csv` cạnh file `.spec.js` | một `it` `<tên> (row N)` |
+| `playwright-go` | `testdata/<tên>.csv`, kèm file hỗ trợ `testgen_data_test.go` | một subtest `row_N` (`go test -run 'TestLogin/row_2'`) |
+
+- **Dòng trong CSV:** dòng đầu là tên cột, dòng thứ hai là giá trị lúc ghi. Thêm dòng để thêm bộ dữ liệu.
+- **Không ghi đè:** testgen không bao giờ ghi đè file CSV đã có (báo `kept`). Muốn sinh lại từ đầu thì xóa file đó.
+- **Tên cột** lấy theo ô nhập hoặc phần tử được assert: `Email` → `email`, placeholder `Tìm kiếm sản phẩm...` → `timKiemSanPham`, assert trên `getByTestId("welcome")` → `expectedWelcome`. Gõ cùng một giá trị nhiều lần thì dùng chung một cột.
+- **Locator đi theo dữ liệu** khi chữ trong locator bằng, hoặc chứa nguyên từ, một giá trị đã gõ trước đó. Ví dụ tìm "Những Kẻ Mê Sách" rồi bấm link "Những Kẻ Mê Sách": link dùng chung cột với từ khóa. Thêm việc "Buy milk" rồi bấm nút xóa của mục "Buy milk Delete": locator thành `filterHasText(whatNeedsToBeDone + " Delete")`. Giá trị ngắn hơn 3 ký tự chỉ được thay khi khớp nguyên văn, vì "1" có thể là một phần của bất kỳ số nào. Các chữ khác giữ nguyên như lúc ghi.
+- **Assert là cột riêng:** chữ mong đợi như `Welcome, qa@example.com (jp)` là một cột riêng, kể cả khi nó chứa giá trị đã gõ. Mỗi dòng phải điền đúng chữ mong đợi của dòng đó.
+- **Mở bằng Excel:** file sinh ra có BOM để Excel hiện đúng tiếng Việt. Mọi target đọc được cả dấu phẩy lẫn dấu chấm phẩy (Excel ở một số ngôn ngữ lưu bằng `;`), bỏ qua dòng trống và các cột thừa, ví dụ một cột `note` để mô tả từng dòng.
+
 ## Cách hoạt động
 
 ```
@@ -136,16 +277,18 @@ Bên dưới vẫn là Selenium WebDriver: các hành động dùng `WebElement.
         │  selector → chuỗi locator: dùng lại mã của Playwright (src/vendor/playwright)
         ▼
  Generators (src/generators/*)
-   ├─ playwright-ts   giống `playwright codegen --target playwright-test`
-   ├─ playwright-go   API playwright-go + require.NoError
-   ├─ selenium-java   JUnit 5 + TestgenSupport.java
-   └─ selenium-js     Mocha + testgen-support.js
-                          └─ runtime/selenium/engine.js: chạy trong trang (executeScript)
-                             để tìm element theo role / text / label / test id… như Playwright
+   ├─ playwright-ts          giống `playwright codegen --target playwright-test`
+   ├─ playwright-go          API playwright-go + require.NoError
+   ├─ selenium-java          JUnit 5 + TestgenSupport.java
+   ├─ selenium-java-testng   TestNG + TestgenSupport.java
+   └─ selenium-js            Mocha + testgen-support.js
+                                 └─ runtime/selenium/engine.js: chạy trong trang (executeScript)
+                                    để tìm element theo role / text / label / test id… như Playwright
 ```
 
 - **Recorder:** dùng nguyên recorder của Playwright, nên cách chọn locator (ưu tiên test id, role + tên, label…) giống hệt Playwright codegen.
 - **Engine locator cho Selenium:** được kiểm tra bằng cách so kết quả với chính Playwright trên 70 locator mẫu (`test/engine.test.ts`).
+- **Giữa bản ghi và generators:** `src/secrets.ts` tìm các bước secret, `src/generators/test-data.ts` quyết định mỗi giá trị là chữ, cột CSV hay biến môi trường, `src/checks.ts` tạo cảnh báo. Giao diện sửa bản ghi bằng `src/editing.ts` (locator gõ tay được đổi lại thành selector bằng mã của Playwright) và chạy lại bằng `src/replay.ts` (`playwright-core`).
 
 ## Giới hạn hiện tại
 
@@ -158,7 +301,11 @@ Bên dưới vẫn là Selenium WebDriver: các hành động dùng `WebElement.
   - `colorScheme` / `timezone` / `geolocation`;
   - lưu storage state.
 - **`getByRole` trên Selenium chỉ gần đúng**, vì thuật toán tính accessible name được đơn giản hóa. Khi gặp sai lệch, hãy thêm `data-testid` cho app, hoặc thêm trường hợp đó vào `test/engine.test.ts`.
-- **Bản ghi không lưu đường dẫn đầy đủ của file upload**, chỉ có tên file. Cần sửa đường dẫn trong `setInputFiles(...)`.
+- **Bản ghi không lưu đường dẫn đầy đủ của file upload**, chỉ có tên file. Sửa bước đó trong giao diện (ô **Files**, mỗi dòng một đường dẫn) hoặc sửa `setInputFiles(...)` trong test. Replay bỏ qua bước upload khi không tìm thấy file.
+- **Replay chạy bản ghi trên Playwright**, không chạy code đã sinh. Replay qua không bảo đảm test Selenium qua, vì `getByRole` trên Selenium chỉ gần đúng (xem trên). Muốn chắc thì chạy chính test đã sinh, như `npm run e2e` làm với app demo.
+- **Phát hiện secret dựa vào locator**, không dựa vào `type="password"` của ô. Ô không có nhãn hay id gợi ý (ví dụ `#field3`) sẽ không được nhận ra: xem mục **Checks** và bật ô **Secret** trong giao diện. Ngược lại, ô có chữ "password" trong tên mà không phải mật khẩu thì tắt đi.
+- **Report và trace của Playwright vẫn hiện giá trị gõ vào ô**, kể cả giá trị đọc từ biến môi trường. Đừng chia sẻ chúng ra ngoài nếu test dùng mật khẩu thật.
+- **`--log-steps` chỉ dành cho Selenium.** Hai target Playwright bỏ qua tùy chọn này, CLI và giao diện có ghi chú khi bỏ qua.
 
 ## Phát triển
 
@@ -167,7 +314,7 @@ Package trên npm chỉ chứa bản build. Để sửa code thì làm việc tr
 ```bash
 npm ci            # tự build (script prepare); gọi tool bằng `node dist/cli.js`
 npm test          # vitest: so engine với Playwright, snapshot code sinh ra, test giao diện (cần Chrome)
-npm run e2e       # sinh test cho cả 4 target rồi chạy trên app demo e2e/app (cần Go, JDK 17+ và Maven, Chrome)
+npm run e2e       # sinh test cho mọi target rồi chạy trên app demo e2e/app (cần Go, JDK 17+ và Maven, Chrome)
 E2E_TARGETS="selenium-js playwright-go" npm run e2e
 ```
 
@@ -185,8 +332,36 @@ runtime/        file hỗ trợ Selenium (Java, JS) + engine locator chạy tron
 ui/             giao diện web (HTML/CSS/JS thuần, không cần build)
 test/           unit test, fixture, snapshot
 e2e/            app demo, bản ghi thật, project mẫu cho từng target, run.sh
+scripts/        script phát hành lên npm (release.mjs)
+```
+
+### Phát hành lên npm
+
+GitLab CI ([.gitlab-ci.yml](.gitlab-ci.yml)) chạy test cho mọi lần push. Phát hành một version mới:
+
+1. Ghi thay đổi vào mục `## Chưa phát hành` ở đầu `CHANGELOG.md` rồi commit.
+2. Chạy `npm run release -- patch` (hoặc `minor`, `major`, `1.2.3`). Script kiểm tra, chạy test, tăng version trong `package.json` và `package-lock.json`, đổi `## Chưa phát hành` thành `## <version> (<ngày>)`, commit `chore: release <version>`, rồi push `main` cùng tag `v<version>`.
+3. Pipeline của tag chạy test, rồi đưa version đó vào khu chờ duyệt của npm (`npm stage publish`).
+4. Duyệt bằng 2FA để version lên npm: `npm stage list @xylentis/testgen` rồi `npm stage approve <stage-id>`, hoặc bấm **Approve** ở tab **Staged Packages** trên trang package ở npmjs.com.
+
+```bash
+npm run release -- patch        # hoặc minor, major, 1.2.3
+npm run release                 # phát hành version đang có trong package.json (CHANGELOG.md phải có mục `## <version>`)
+npm run release -- --dry-run    # chạy thử: kiểm tra, test và `npm pack --dry-run`, không thay đổi gì
 ```
 
+Trước khi tag, script kiểm tra: đang ở nhánh `main`, không có thay đổi chưa commit, không chậm hơn `origin/main`, version chưa có trên npm và mới hơn version `latest`, chưa có tag `v<version>`. `npm run e2e` cần Go, JDK và Maven nên không chạy trong script hay CI; hãy tự chạy khi đổi generator hay runtime Selenium.
+
+**Vì sao vẫn phải duyệt tay:** npm chưa hỗ trợ trusted publishing (OIDC) cho GitLab tự host. Token bỏ qua 2FA cũng sẽ mất quyền publish thẳng từ tháng 1/2027. CI vì vậy chỉ dùng token "stage only": lộ token thì cũng không publish được.
+
+**Duyệt theo thứ tự version.** Version được duyệt sẽ thành `latest`, kể cả khi đã có version mới hơn. Bản stage không dùng nữa thì xóa bằng `npm stage reject <stage-id>`.
+
+**Cài đặt một lần:**
+
+1. Trên npmjs.com: **Access Tokens → Generate New Token**, quyền **Read and write (stage only)**, chỉ cho package `@xylentis/testgen`. Token có quyền ghi hết hạn sau tối đa 90 ngày, nên cần tạo lại định kỳ.
+2. Lưu token vào biến CI/CD `NPM_TOKEN` của project, bật **Masked** và **Protected**: trong GitLab (**Settings → CI/CD → Variables**), hoặc copy token rồi chạy `pbpaste | glab variable set NPM_TOKEN --masked --protected`.
+3. Bảo vệ tag `v*` (**Settings → Repository → Protected tags**) để pipeline của tag nhận được biến protected: `glab api -X POST projects/:id/protected_tags -f name='v*' -f create_access_level=40`.
+
 ## License
 
 [GNU AGPL-3.0-only](LICENSE), Copyright (C) 2026 Xylentis.

package/dist/checks.js

@@ -0,0 +1,100 @@
+import { parseLocator } from './locator.js';
+import { collectSecrets } from './secrets.js';
+// Actions whose effect an assertion should verify.
+const changes = new Set(['click', 'fill', 'press', 'select', 'check', 'uncheck', 'setInputFiles']);
+export function checkRecording(recording) {
+    const { actions } = recording;
+    const checks = [];
+    const secrets = collectSecrets(recording);
+    const lastAssertion = actions.findLastIndex(({ action }) => action.name.startsWith('assert'));
+    if (lastAssertion === -1 && actions.some(({ action }) => changes.has(action.name)))
+        checks.push({ level: 'warning', message: 'No assertion: the test shows that the steps run, not that they work. Add checks with the recorder toolbar (Assert visibility, text, value).' });
+    let locators = 0;
+    let textLocators = 0;
+    let testIds = 0;
+    actions.forEach(({ action }, index) => {
+        const step = index + 1;
+        if ('selector' in action) {
+            const steps = parseLocator(action.selector);
+            const position = positionOf(steps);
+            if (position)
+                checks.push({ level: 'warning', step: index, message: `Step ${step} finds its element by position (${position}): it breaks when elements are added or reordered. A test id, or a role and name, is more stable.` });
+            const structure = structureOf(steps);
+            if (structure)
+                checks.push({ level: 'warning', step: index, message: `Step ${step} depends on the page structure (${structure}): it breaks when the layout changes.` });
+            locators++;
+            if (dependsOnText(steps))
+                textLocators++;
+            if (allSteps(steps).some(s => s.kind === 'test-id'))
+                testIds++;
+        }
+        if (action.name === 'setInputFiles')
+            checks.push({ level: 'warning', step: index, message: `Step ${step} uploads ${action.files.join(', ')}: recordings keep only file names. Set the full paths by editing the step.` });
+        const secret = secrets.of(index);
+        if (secret && action.name === 'fill')
+            checks.push({ level: 'info', step: index, message: `Step ${step} types into a password field: the test reads the value from the environment variable ${secret.name}.` });
+    });
+    if (lastAssertion !== -1) {
+        const unchecked = actions.findIndex(({ action }, index) => index > lastAssertion && changes.has(action.name));
+        if (unchecked !== -1)
+            checks.push({ level: 'info', step: unchecked, message: `No assertion follows step ${unchecked + 1}: add one to verify what the last steps do.` });
+    }
+    if (textLocators && !testIds)
+        checks.push({ level: 'info', message: `${textLocators} of ${locators} locators use visible text (role names, labels, text): they break when the wording or the language of the page changes. Test ids (data-testid) are more stable.` });
+    return checks;
+}
+// What a target cannot do: the TODO(testgen) comments of its generated test.
+export function checkFiles(files) {
+    const counts = new Map();
+    for (const file of files.filter(f => !f.support && !f.data)) {
+        for (const [, message] of file.content.matchAll(/TODO\(testgen\): (.*)/g))
+            counts.set(message, (counts.get(message) ?? 0) + 1);
+    }
+    return [...counts].map(([message, count]) => ({ level: 'warning', message: `TODO(testgen) in the code: ${message}${count > 1 ? ` (${count} times)` : ''}` }));
+}
+function allSteps(steps) {
+    return steps.flatMap(step => [step, ...allSteps(step.inner ?? [])]);
+}
+function positionOf(steps) {
+    const step = allSteps(steps).find(s => s.kind === 'nth' || s.kind === 'first' || s.kind === 'last');
+    return step && (step.kind === 'nth' ? `nth(${step.body})` : `${step.kind}()`);
+}
+// An XPath or a CSS selector with combinators or :nth-child(), as in "#list > li:nth-child(2)".
+function structureOf(steps) {
+    for (const step of allSteps(steps)) {
+        if (step.kind !== 'default')
+            continue;
+        const css = String(step.body);
+        if (/^(xpath=|\/\/|\.\.)/.test(css))
+            return css;
+        // Combinators outside of attribute values and quotes.
+        const outside = css.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\[[^\]]*\]|\([^)]*\)/g, '');
+        if (/[>+~\s]|:nth-/.test(outside.trim()) || /:nth-/.test(css))
+            return css;
+    }
+    return undefined;
+}
+// Whether the element is found by text a page shows: a role and name, a label, a text...
+function dependsOnText(steps) {
+    for (const step of [...steps].reverse()) {
+        switch (step.kind) {
+            case 'role':
+                return step.name !== undefined;
+            case 'text':
+            case 'label':
+            case 'placeholder':
+            case 'alt':
+            case 'title':
+                return true;
+            case 'test-id':
+            case 'default':
+                return false;
+            case 'and':
+            case 'or':
+            case 'chain':
+                return dependsOnText(step.inner);
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=checks.js.map