chrometools-mcp 3.5.4 → 3.5.6

package/SPEC-pom-integration.md

@@ -1,227 +0,0 @@
-# Спецификация: Интеграция Page Object Model в экспортируемые тесты
-
-## Контекст
-
-QA-автоматизаторы жалуются, что тесты, экспортируемые через `exportScenarioAsCode` / `appendScenarioToFile`, **не используют Page Object**. Даже при `generatePageObject: true` генерируются два несвязанных файла — тест с raw-селекторами и POM-класс отдельно.
-
-**Сейчас** (raw-селекторы):
-```typescript
-test('login', async ({ page }) => {
-  await page.goto('https://example.com/login');
-  await page.locator('#username').fill('admin');
-  await page.locator('#password').fill('secret');
-  await page.locator('#login-btn').click();
-});
-```
-
-**Нужно** (POM-интеграция):
-```typescript
-import { LoginPage } from './LoginPage';
-
-test('login', async ({ page }) => {
-  const loginPage = new LoginPage(page);
-  await loginPage.goto();
-  await loginPage.fillUsername('admin');
-  await loginPage.fillPassword('secret');
-  await loginPage.clickLoginBtn();
-});
-```
-
-## Подход
-
-Добавить новый параметр `pageObjectMode` к тулам экспорта. Два сценария:
-
-1. **`generate-integrated`** — сгенерировать POM + тест, который его использует
-2. **`use-existing`** — прочитать существующий POM-файл, сгенерировать тест, который его использует
-
-Ключевой механизм — **selector matching**: сопоставление селекторов из записанного сценария с локаторами POM-элементов.
-
-## Изменения по файлам
-
-### 1. Новый файл: `utils/code-generators/pom-integrator.js`
-
-Модуль связки POM с экшнами сценария:
-
-- **`matchActionToPomElement(actionSelector, pomElements)`** — сопоставляет селектор экшна с элементом POM:
-  1. Exact match (`#username` === `#username`)
-  2. Normalized match (strip tag prefix: `input#username` → `#username`)
-  3. Key-based match (извлечь id/name/data-testid и сравнить значения)
-  4. Не найдено → null (fallback на raw-селектор)
-
-- **`parsePomFile(fileContent, framework)`** — парсит существующий POM-файл regex'ами, возвращает `{ className, elements: [{name, selector, methodName, methodType}] }`:
-  - Playwright TS: ищет `this.X = page.locator('...')` и `async fillX(` / `async clickX(`
-  - Playwright Python: ищет `self.X = page.locator('...')` и `def fill_X(` / `def click_X(`
-  - Selenium Python: ищет `X = (By.CSS_SELECTOR, '...')` и `def fill_X(` / `def click_X(`
-  - Selenium Java: ищет `By X = By.cssSelector("...")` и `void fillX(` / `void clickX(`
-
-### 2. Изменить: `recorder/page-object-generator.js`
-
-Добавить в return `generatePageObject()` поле **`elements`** — массив структурированных метаданных:
-```js
-elements: uniqueElements.map(el => ({
-  name: sanitizeIdentifier(el.name, lang),
-  selector: el.selector,
-  tag: el.tag,
-  type: el.type,
-  methodName: generateMethodName(el, framework), // "fillUsername" / "clickSubmit"
-  methodType: getMethodType(el)  // "fill" | "click" | "select"
-}))
-```
-Добавить вспомогательные функции `generateMethodName()` и `getMethodType()` (логика уже есть в `generateActionMethods()`, нужно её вынести).
-
-### 3. Изменить: `utils/code-generators/code-generator-base.js`
-
-Добавить в конструктор опции `pomElements`, `pomClassName`, `pomImportPath`.
-
-Добавить методы с дефолтными реализациями (no-op):
-- `generatePomImports(className, importPath)` → `[]`
-- `generatePomInstantiation(className)` → `[]`
-- `generatePomAction(action, pomElement)` → `null` (значит fallback)
-
-Модифицировать `generate()` и `generateTestOnly()`:
-```js
-// После generateImports(), если POM mode:
-if (this.options.pomClassName) {
-  lines.push(...this.generatePomImports(this.options.pomClassName, this.options.pomImportPath));
-}
-
-// После generateTestHeader(), если POM mode:
-if (this.options.pomClassName) {
-  lines.push(...this.generatePomInstantiation(this.options.pomClassName));
-}
-
-// В цикле экшнов:
-for (const action of scenario.chain) {
-  let actionCode = null;
-  if (this.options.pomElements) {
-    const match = matchActionToPomElement(this.prepareSelector(action), this.options.pomElements);
-    if (match) {
-      actionCode = this.generatePomAction(action, match);
-    }
-  }
-  if (!actionCode) {
-    actionCode = this.generateAction(action);
-  }
-  if (actionCode?.length > 0) lines.push(...actionCode);
-}
-```
-
-Специальная обработка `navigate` → если URL совпадает с POM entryUrl, заменить на `pomInstance.goto()`.
-
-### 4. Изменить: `playwright-typescript.js`
-
-Реализовать 3 POM-метода:
-```js
-generatePomImports(className, importPath) {
-  return [`import { ${className} } from '${importPath || './' + className}';`];
-}
-
-generatePomInstantiation(className) {
-  const varName = className.charAt(0).toLowerCase() + className.slice(1);
-  return [this.indent(`const ${varName} = new ${className}(page);`), ''];
-}
-
-generatePomAction(action, pomElement) {
-  const varName = this.options.pomClassName.charAt(0).toLowerCase() + this.options.pomClassName.slice(1);
-  // fill → await varName.fillUsername('text');
-  // click → await varName.clickSubmit();
-  // select → await varName.selectCountry('US');
-  // other → await varName.elementName.hover();
-}
-```
-
-### 5. Изменить: `playwright-python.js`
-
-```python
-# Import: from login_page import LoginPage
-# Instantiation: login_page = LoginPage(page)
-# Fill: login_page.fill_username('text')
-# Click: login_page.click_submit()
-```
-
-### 6. Изменить: `selenium-python.js`
-
-```python
-# Import: from login_page import LoginPage
-# Instantiation: login_page = LoginPage(driver)
-# Fill: login_page.fill_username('text')
-# Click: login_page.click_submit()
-```
-
-### 7. Изменить: `selenium-java.js`
-
-```java
-// Import: import pages.LoginPage;
-// Instantiation: LoginPage loginPage = new LoginPage(driver);
-// Fill: loginPage.fillUsername("text");
-// Click: loginPage.clickSubmit();
-```
-
-### 8. Изменить: `server/tool-schemas.js`
-
-Добавить к `ExportScenarioAsCodeSchema` и `AppendScenarioToFileSchema`:
-```js
-pageObjectMode: z.enum(['none', 'generate', 'generate-integrated', 'use-existing']).optional()
-  .describe("POM integration: 'none' (default), 'generate' (separate POM, current behavior), 'generate-integrated' (POM + test using it), 'use-existing' (test uses existing POM file)"),
-pageObjectFile: z.string().optional()
-  .describe("Path to existing POM file (for 'use-existing' mode)"),
-```
-
-### 9. Изменить: `server/tool-definitions.js`
-
-Обновить описания тулов `exportScenarioAsCode` и `appendScenarioToFile` — добавить `pageObjectMode` и `pageObjectFile` в `inputSchema.properties`.
-
-### 10. Изменить: `index.js` (экспорт-хендлеры)
-
-**`exportScenarioAsCode` (~строка 3321):**
-- При `pageObjectMode === 'generate-integrated'`: сгенерировать POM, передать `pomElements`/`pomClassName` в генератор → получить тест с POM-вызовами
-- При `pageObjectMode === 'use-existing'`: прочитать POM-файл через `FileAppender.readFile()`, распарсить через `parsePomFile()`, передать в генератор
-- При `pageObjectMode === 'generate'` или `generatePageObject: true`: текущее поведение (обратная совместимость)
-
-**`appendScenarioToFile` (~строка 3182):**
-- Аналогичная логика для `generateTestOnly()`
-
-### 11. Обновить: `README.md`
-
-Документировать `pageObjectMode` и `pageObjectFile` параметры для обеих тул.
-
-## Обратная совместимость
-
-- `generatePageObject: true` (bool) — работает как раньше (maps to `pageObjectMode: 'generate'`)
-- Новое поведение только при явном `pageObjectMode: 'generate-integrated'` или `'use-existing'`
-- Fallback: если экшн не сматчился с POM-элементом — raw-селектор (как сейчас)
-
-## Алгоритм Selector Matching
-
-| Action selector | POM selector | Результат |
-|---|---|---|
-| `#username` | `#username` | Exact match |
-| `input#username` | `#username` | Normalized (strip tag) |
-| `[name="email"]` | `[name="email"]` | Exact match |
-| `input[name="email"]` | `[name="email"]` | Key match (name=email) |
-| `.complex > path:nth(2)` | `#username` | No match → raw fallback |
-
-## Порядок реализации
-
-1. `page-object-generator.js` — добавить `elements` metadata + helper-функции
-2. `pom-integrator.js` — создать (matching + parsing)
-3. `code-generator-base.js` — POM-методы + модифицированный generate-цикл
-4. `playwright-typescript.js` — имплементация POM-методов (reference)
-5. `playwright-python.js` — имплементация POM-методов
-6. `selenium-python.js` — имплементация POM-методов
-7. `selenium-java.js` — имплементация POM-методов
-8. `tool-schemas.js` — новые параметры
-9. `tool-definitions.js` — обновить descriptions + schema
-10. `index.js` — оркестрация в хендлерах экспорта
-11. `README.md` — документация
-
-## Верификация
-
-1. Записать сценарий на тестовой странице (например, Google Search)
-2. Вызвать `exportScenarioAsCode` с `pageObjectMode: 'generate-integrated'`
-3. Проверить что тест-файл содержит import POM-класса и вызывает его методы
-4. Вызвать `generatePageObject`, сохранить файл, затем `exportScenarioAsCode` с `pageObjectMode: 'use-existing'`
-5. Проверить что тест использует существующий POM
-6. Проверить fallback: экшны без матча → raw-селекторы
-7. Проверить все 4 фреймворка
-8. Проверить `appendScenarioToFile` с POM-интеграцией