@xylentis/testgen 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 - 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.
 - Thêm `testgen record --inspector` để hiện lại Inspector khi cần.
+- 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.0.0 (2026-10-05)
 

package/README.md

@@ -46,7 +46,8 @@ testgen ui                  # mở http://127.0.0.1:9323
 
 Một số thao tác khác:
 
-- **Đổi Test name / Package / Test id attribute:** code sinh lại ngay.
+- **Đổ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.
 - **Download recording:** lưu file `.jsonl` để lần sau sinh lại.
 - **Open recording…:** mở lại một file đã lưu.
 
@@ -74,11 +75,38 @@ 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`). |
+| `--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. |
 | `--save` | (`record`) Nơi lưu bản ghi `.jsonl`. |
 | `--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.
+
 ## 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.

package/dist/cli.js

@@ -6,7 +6,7 @@ import { parseArgs } from 'node:util';
 import { generateTargets, writeTargets } from './generate.js';
 import { generators } from './generators/index.js';
 import { startCodegen, waitForExit } from './record.js';
-import { parseRecording } from './recording.js';
+import { parseRecording, recordedTestIdAttribute } from './recording.js';
 import { startUiServer } from './ui/server.js';
 const usage = `testgen: record a UI test once with the Playwright recorder, then generate it for several
 frameworks and languages.
@@ -24,7 +24,8 @@ Output options:
                                (default for record: ./generated)
   -n, --name <name>            Test name (default: taken from --output, else "recorded")
       --package <name>         Java or Go package (default: derived from the output path)
-      --test-id-attribute <a>  Attribute used by getByTestId (default: data-testid)
+      --test-id-attribute <a>  Attribute for getByTestId when recording (default: data-testid);
+                               generated code keeps the one the recording was made with
       --save <file.jsonl>      record: where to keep the recording (default: <out-dir>/recording.jsonl)
 
 Recorder options (record), same as playwright codegen:
@@ -39,7 +40,7 @@ const options = {
     'out-dir': { type: 'string', short: 'd' },
     'name': { type: 'string', short: 'n' },
     'package': { type: 'string' },
-    'test-id-attribute': { type: 'string', default: 'data-testid' },
+    'test-id-attribute': { type: 'string' },
     'save': { type: 'string' },
     'browser': { type: 'string', short: 'b' },
     'channel': { type: 'string' },
@@ -66,12 +67,13 @@ async function main(argv) {
         return;
     }
     const targets = values.target ? values.target.split(',').map(t => t.trim()).filter(Boolean) : generators.map(g => g.id);
+    const testIdAttribute = values['test-id-attribute'] ?? 'data-testid';
     const output = {
         targets,
         output: values.output,
         name: values.name,
         packageName: values.package,
-        testIdAttribute: values['test-id-attribute'],
+        testIdAttribute,
     };
     switch (command) {
         case 'targets':
@@ -83,6 +85,9 @@ async function main(argv) {
             if (!file)
                 throw new Error('Usage: testgen generate <recording.jsonl> [options]');
             const recording = parseRecording(fs.readFileSync(file, 'utf8'), file);
+            const recorded = recordedTestIdAttribute(recording);
+            if (values['test-id-attribute'] && recorded && recorded !== values['test-id-attribute'])
+                console.error(`note: ignoring --test-id-attribute ${values['test-id-attribute']}: the recording's getByTestId() steps use ${recorded}.`);
             if (!values.output && !values['out-dir']) {
                 if (targets.length !== 1)
                     throw new Error('Pass --out-dir (or a single --target to print the test to stdout).');
@@ -112,7 +117,7 @@ async function main(argv) {
                 ignoreHttpsErrors: values['ignore-https-errors'],
                 loadStorage: values['load-storage'],
                 saveStorage: values['save-storage'],
-                testIdAttribute: values['test-id-attribute'],
+                testIdAttribute,
                 inspector: values.inspector,
             };
             console.log('Recording... interact with the page, then close the browser window (or press Ctrl+C) to generate the tests.');

package/dist/generate.js

@@ -2,11 +2,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { findGenerator } from './generators/index.js';
 import { nameFromFileName } from './naming.js';
+import { recordedTestIdAttribute } from './recording.js';
 export function generateTargets(recording, options) {
     if (!options.targets.length)
         throw new Error('Pick at least one target with --target.');
     if (options.output && options.targets.length > 1)
         throw new Error('--output takes a single target; use --out-dir for several targets.');
+    const testIdAttribute = recordedTestIdAttribute(recording) ?? options.testIdAttribute;
     return options.targets.map(id => {
         const generator = findGenerator(id);
         const directory = options.output
@@ -14,7 +16,7 @@ export function generateTargets(recording, options) {
             : path.join(options.outDir ?? '.', options.targets.length > 1 ? generator.id : '');
         const name = options.name ?? (options.output ? nameFromFileName(options.output) : 'recorded');
         const packageName = options.packageName ?? defaultPackage(generator, directory);
-        const files = generator.generate(recording, { name, packageName, testIdAttribute: options.testIdAttribute });
+        const files = generator.generate(recording, { name, packageName, testIdAttribute });
         if (options.output)
             files[0] = { ...files[0], path: path.basename(options.output) };
         return { generator, directory, files };

package/dist/locator.js

@@ -1,4 +1,5 @@
 import { asLocator, asLocatorWithFactory } from './vendor/playwright/locatorGenerators.js';
+import { parseAttributeSelector, parseSelector, visitAllSelectorParts } from './vendor/playwright/selectorParser.js';
 const nestedKinds = ['has', 'hasNot', 'and', 'or', 'chain'];
 export function isRegex(matcher) {
     return typeof matcher === 'object' && matcher !== null;
@@ -46,4 +47,20 @@ export function parseLocator(selector) {
 export function describeSelector(selector) {
     return asLocator('javascript', selector);
 }
+// Attributes behind the selector's getByTestId() calls: internal:testid=[data-testid="welcome"s]
+// gives ['data-testid']. The locator itself only keeps the test id ("welcome").
+export function testIdAttributesOf(selector) {
+    const names = [];
+    try {
+        visitAllSelectorParts(parseSelector(selector), part => {
+            // Several attributes are one comma-separated name, as in Playwright's testIdAttribute option.
+            if (part.name === 'internal:testid')
+                names.push(...parseAttributeSelector(part.body, true).attributes[0].name.split(','));
+        });
+    }
+    catch {
+        // Not a selector Playwright can parse; it has no getByTestId() call.
+    }
+    return names;
+}
 //# sourceMappingURL=locator.js.map

package/dist/recording.js

@@ -1,3 +1,4 @@
+import { testIdAttributesOf } from './locator.js';
 const defaultHeader = { browserName: 'chromium', launchOptions: {}, contextOptions: {} };
 export function parseRecording(text, source = 'recording') {
     let header;
@@ -48,6 +49,22 @@ export function signalsOf(actionInContext) {
         expect: find('expect'),
     };
 }
+// The test id attribute the recording was made with (`--test-id-attribute`), read back from its
+// getByTestId() selectors; undefined when there are none. Generated getByTestId() calls only keep
+// the test id, so the generated code has to configure this same attribute.
+export function recordedTestIdAttribute(recording) {
+    const names = new Set();
+    for (const { action, signals } of recording.actions) {
+        const selectors = signals.flatMap(signal => signal.name === 'expect' ? [signal.selector] : []);
+        if ('selector' in action)
+            selectors.push(action.selector);
+        for (const selector of selectors) {
+            for (const name of testIdAttributesOf(selector))
+                names.add(name);
+        }
+    }
+    return names.size ? [...names].join(',') : undefined;
+}
 // Mirrors Playwright's codegen: the first page and every page opened later get stable names
 // ("page", "page1", ...), assigned in the order the recording mentions them.
 export class PageAliases {

package/dist/ui/server.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { generateTargets, writeTargets } from '../generate.js';
 import { generators } from '../generators/index.js';
 import { describeSelector } from '../locator.js';
-import { PageAliases, parseRecording } from '../recording.js';
+import { PageAliases, parseRecording, recordedTestIdAttribute } from '../recording.js';
 import { startCodegen } from '../record.js';
 const uiRoot = new URL('../../ui/', import.meta.url);
 const staticFiles = {
@@ -216,7 +216,7 @@ function render(state) {
     }
     const aliases = new PageAliases();
     const steps = recording.actions.map(({ action, pageGuid }) => ({ page: aliases.alias(pageGuid), text: describeAction(action) }));
-    return { steps, outputs };
+    return { steps, outputs, recordedTestIdAttribute: recordedTestIdAttribute(recording) };
 }
 function describeAction(action) {
     const target = 'selector' in action ? describeSelector(action.selector) : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylentis/testgen",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Record a UI test once with the Playwright recorder, then generate it for Playwright (TypeScript, Go) and Selenium (Java, JavaScript).",
   "keywords": [
     "playwright",
@@ -49,4 +49,4 @@
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"
   }
-}
+}

package/ui/app.js

@@ -71,6 +71,12 @@ function render() {
     if (document.activeElement !== input && snapshot.settings[key] !== undefined)
       input.value = snapshot.settings[key];
   }
+  // The code keeps the test id attribute the recording was made with; the field is for the next one.
+  const recorded = snapshot.recordedTestIdAttribute;
+  const next = snapshot.settings.testIdAttribute;
+  $('test-id-note').textContent = recorded && next && recorded !== next
+    ? `This recording was made with "${recorded}", so the code keeps it. "${next}" applies to the next recording.`
+    : '';
   renderTargets();
   renderCode();
 }

package/ui/index.html

@@ -27,7 +27,8 @@
   <section class="options" aria-label="Generation options">
     <label>Test name <input id="name" value="recorded" spellcheck="false"></label>
     <label>Package <input id="package" placeholder="e.g. com.acme.e2e" spellcheck="false"></label>
-    <label>Test id attribute <input id="test-id" value="data-testid" spellcheck="false"></label>
+    <label>Test id attribute <input id="test-id" value="data-testid" spellcheck="false" aria-describedby="test-id-note"></label>
+    <span id="test-id-note" class="note" role="status"></span>
     <span class="spacer"></span>
     <label class="file-button">Open recording… <input id="open" type="file" accept=".jsonl,.json,.txt"></label>
     <a id="download-recording" class="button" href="/api/recording" download="recording.jsonl">Download recording</a>

package/ui/style.css

@@ -102,6 +102,7 @@ body.recording .status { color: var(--recording); font-weight: 600; }
 .file-button { border: 1px solid var(--border); border-radius: 6px; padding: 4px 10px; cursor: pointer; color: var(--text); }
 .file-button input { display: none; }
 .options .button { padding: 4px 10px; }
+.options .note { color: var(--text); }
 
 .error {
   margin: 12px 16px 0;