mirror of
https://github.com/Nikolay-Shirokov/cc-1c-skills.git
synced 2026-06-14 01:44:57 +03:00
Auto-build: copilot (python) from 7fa279c
This commit is contained in:
github-actions[bot]
@@ -0,0 +1,4 @@
|
||||
scripts/node_modules/
|
||||
.browser-session.json
|
||||
*.png
|
||||
*.mp4
|
||||
@@ -0,0 +1,535 @@
|
||||
---
|
||||
name: web-test
|
||||
description: Тестирование 1С через веб-клиент — автоматизация действий в браузере. Используй когда пользователь просит проверить, протестировать, автоматизировать действия в 1С через браузер
|
||||
argument-hint: "сценарий на естественном языке"
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
- Write
|
||||
- Glob
|
||||
- Grep
|
||||
---
|
||||
|
||||
# /web-test — Browser automation for 1C web client
|
||||
|
||||
Automates user interactions with 1C:Enterprise web client via Playwright — navigating sections, filling forms, reading tables and reports, filtering lists.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
RUN=".github/skills/web-test/scripts/run.mjs"
|
||||
|
||||
# One-shot: opens browser → runs script → closes browser → exits
|
||||
node $RUN run http://localhost:8081/bpdemo test-scenario.js
|
||||
|
||||
# Or pipe inline:
|
||||
cat <<'SCRIPT' | node $RUN run http://localhost:8081/bpdemo -
|
||||
await navigateSection('Продажи');
|
||||
await openCommand('Заказы клиентов');
|
||||
await clickElement('Создать');
|
||||
await fillFields({ 'Клиент': 'Альфа' });
|
||||
await clickElement('Провести и закрыть');
|
||||
SCRIPT
|
||||
```
|
||||
|
||||
## Setup (first time)
|
||||
|
||||
```bash
|
||||
cd ".github/skills/web-test/scripts" && npm install
|
||||
```
|
||||
|
||||
Requires Node.js 18+. `npm install` downloads Playwright and Chromium.
|
||||
|
||||
## URL resolution
|
||||
|
||||
Read `.v8-project.json` from project root. Each database has `id` and optional `webUrl`.
|
||||
Construct URL as `http://localhost:8081/<id>` or use `webUrl` if set.
|
||||
Use `/web-publish` first if the database is not published.
|
||||
|
||||
## Execution modes
|
||||
|
||||
### Autonomous mode (preferred for complete scenarios)
|
||||
|
||||
```bash
|
||||
node $RUN run <url> script.js # exits when done, no session
|
||||
```
|
||||
|
||||
### Interactive mode (step-by-step development)
|
||||
|
||||
```bash
|
||||
# 1. Start session (run_in_background=true, prints JSON when ready)
|
||||
node $RUN start <url>
|
||||
|
||||
# 2. Execute scripts against running session
|
||||
cat <<'SCRIPT' | node $RUN exec -
|
||||
const form = await getFormState();
|
||||
console.log(JSON.stringify(form, null, 2));
|
||||
SCRIPT
|
||||
|
||||
# 2b. Execute without video recording (for debugging/testing)
|
||||
cat script.js | node $RUN exec - --no-record
|
||||
|
||||
# 3. Screenshot
|
||||
node $RUN shot result.png
|
||||
|
||||
# 4. Stop (logout + close)
|
||||
node $RUN stop
|
||||
```
|
||||
|
||||
`start` runs an HTTP server in background. Use `exec`/`shot`/`stop` from other shells.
|
||||
|
||||
### Writing exec scripts
|
||||
|
||||
All browser.mjs exports are globals — no `import` needed.
|
||||
`console.log()` output is captured in the JSON response.
|
||||
`writeFileSync` / `readFileSync` also available.
|
||||
|
||||
## API reference
|
||||
|
||||
### Navigation
|
||||
|
||||
#### `navigateSection(name)` → `{ navigated, sections, commands }`
|
||||
Go to a top-level section (fuzzy match). Returns list of commands in that section.
|
||||
```js
|
||||
await navigateSection('Продажи');
|
||||
// { navigated: 'Продажи', sections: [...], commands: ['Заказы клиентов', ...] }
|
||||
```
|
||||
|
||||
#### `openCommand(name)` → form state
|
||||
Open a command from the function panel (fuzzy). Returns form state of the opened form.
|
||||
```js
|
||||
const form = await openCommand('Заказы клиентов');
|
||||
```
|
||||
|
||||
#### `navigateLink(url)` → form state
|
||||
Open any 1C object by metadata path (Shift+F11 dialog). Bypasses section/command navigation.
|
||||
```js
|
||||
await navigateLink('Документ.ЗаказКлиента');
|
||||
await navigateLink('РегистрНакопления.ЗаказыКлиентов');
|
||||
await navigateLink('Справочник.Контрагенты');
|
||||
```
|
||||
|
||||
#### `openFile(path)` → form state
|
||||
Open an external data processor or report (EPF/ERF) via File → Open. Handles the security confirmation dialog automatically.
|
||||
```js
|
||||
const form = await openFile('C:\\WS\\build\\МояОбработка.epf');
|
||||
const form = await openFile('build/МояОбработка.epf'); // relative paths work too
|
||||
```
|
||||
|
||||
#### `switchTab(name)` → form state
|
||||
Switch to an already-open tab/window (fuzzy match).
|
||||
|
||||
### Reading form state
|
||||
|
||||
#### `getFormState()` → `{ form, formCount, openForms, fields, buttons, tabs, navigation?, table, tables, filters, reportSettings? }`
|
||||
Returns current form structure. This is the primary way to understand what's on screen.
|
||||
|
||||
**form** — active form number, or `null` when no form is open (desktop).
|
||||
|
||||
**formCount** — number of open forms. Use this to know how many windows are stacked. `0` means desktop.
|
||||
|
||||
**openForms** — array of all open form numbers (e.g. `[0, 1]`). Works even when the open-windows tab bar is hidden in 1C settings.
|
||||
|
||||
**modal** — `true` when the active form is a modal dialog blocking the UI. Only present when modal is active.
|
||||
|
||||
**openTabs** — array of `{ name, active? }` from the open-windows tab bar. Only present when the tab bar is enabled in 1C settings. Do NOT rely on this — use `formCount`/`openForms` instead.
|
||||
|
||||
**fields** — each field has: `name`, `value`, `label?`, `actions?` (select, clear, open), `required?` (true for unfilled mandatory fields)
|
||||
|
||||
**navigation** — form navigation panel links (for objects with subordinate catalogs): `[{ name, active? }]`. Clickable via `clickElement()`. Only present when the form has a navigation panel (e.g. "Основное", "Объекты метаданных", "Подсистемы").
|
||||
|
||||
**tables** — array of all visible grids: `[{ name, columns, rowCount, label? }]`. `label` is the visual group title shown on screen (e.g. "Входящие"), absent when grid has no visible title. Use `readTable()` for actual data.
|
||||
|
||||
**table** — backward-compatible alias for the first grid: `{ present, columns, rowCount }`.
|
||||
|
||||
**reportSettings** — for DCS reports: human-readable filter settings instead of raw technical names:
|
||||
```js
|
||||
const form = await getFormState();
|
||||
// form.reportSettings = [
|
||||
// { name: "Склад", enabled: true, value: "Склад бытовой техники", actions: ["select"] },
|
||||
// { name: "Номенклатура", enabled: false, value: "" }
|
||||
// ]
|
||||
```
|
||||
|
||||
**errorModal** — if present, 1C showed an error dialog. Read the message and decide how to proceed.
|
||||
|
||||
**confirmation** — if present, a Yes/No dialog is shown. Call `clickElement('Да')` or `clickElement('Нет')`.
|
||||
|
||||
**errors.stateText** — array of SpreadsheetDocument state messages (e.g. `"Не установлено значение параметра \"X\""`, `"Отчет не сформирован..."`, `"Изменились настройки..."`). Present when the report area shows an info bar instead of data.
|
||||
|
||||
### Reading data
|
||||
|
||||
#### `readTable({ maxRows?, offset?, table? })` → `{ columns, rows, total, shown, offset }`
|
||||
Read actual grid data with pagination. Each row is `{ columnName: value }`.
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `maxRows` | 20 | Max rows to return per call |
|
||||
| `offset` | 0 | Skip first N rows |
|
||||
| `table` | — | Grid name from `tables[]` (for multi-grid forms) |
|
||||
|
||||
Special row fields:
|
||||
- `_kind: 'group'` — hierarchical group row
|
||||
- `_kind: 'parent'` — parent row in hierarchy
|
||||
- `_tree: 'expanded'|'collapsed'` — tree node state
|
||||
- `_level: N` — nesting depth in tree view
|
||||
- `_selected: true` — row is selected (highlighted). Use with `clickElement({ modifier: 'ctrl'|'shift' })` to verify multi-selection
|
||||
- `hierarchical: true` — list has groups (on result object)
|
||||
- `viewMode: 'tree'` — tree view active (on result object)
|
||||
|
||||
```js
|
||||
const t = await readTable({ maxRows: 50 });
|
||||
console.log('Columns:', t.columns);
|
||||
console.log('Rows:', t.rows.length, 'of', t.total);
|
||||
// Pagination:
|
||||
const page2 = await readTable({ maxRows: 50, offset: 50 });
|
||||
```
|
||||
|
||||
#### `readSpreadsheet()` → `{ title?, headers?, data?, totals?, rows?, total }`
|
||||
Read report output (SpreadsheetDocument) after clicking "Сформировать".
|
||||
|
||||
Returns structured data when header row is detected:
|
||||
```js
|
||||
await clickElement('Сформировать');
|
||||
await wait(5);
|
||||
const report = await readSpreadsheet();
|
||||
// { title: "Остатки товаров", headers: ["Номенклатура", "Склад", "Количество"],
|
||||
// data: [{ "Номенклатура": "Бумага", "Склад": "Основной", "Количество": "150" }, ...],
|
||||
// totals: { "Количество": "1250" }, total: 42 }
|
||||
```
|
||||
|
||||
Falls back to `{ rows: string[][], total }` when headers can't be detected.
|
||||
|
||||
#### `getSections()` → `{ activeSection, sections, commands }`
|
||||
Read section panel and commands without navigating.
|
||||
|
||||
#### `getCommands()` → `string[]`
|
||||
Commands of the current section.
|
||||
|
||||
#### `getPageState()` → `{ activeSection, activeTab, sections, tabs }`
|
||||
Sections + all open tabs.
|
||||
|
||||
### Actions
|
||||
|
||||
#### `clickElement(text, { dblclick?, table?, expand?, modifier? })` → form state
|
||||
Click button, hyperlink, tab, navigation panel link, or grid row (fuzzy match).
|
||||
|
||||
- `table` — scope button search to a specific grid's command panel (by name from `tables[]`):
|
||||
```js
|
||||
await clickElement('Добавить', { table: 'Исходящие' }); // clicks "Добавить" near "Исходящие" grid
|
||||
```
|
||||
- Single click selects a row in a list. **Double-click opens** the item:
|
||||
```js
|
||||
await clickElement('0000-000227', { dblclick: true }); // opens document
|
||||
```
|
||||
- Returns `submenu[]` when a menu opens — click again with item name:
|
||||
```js
|
||||
const r = await clickElement('Ещё');
|
||||
// r.submenu = ['Расширенный поиск', 'Настройки', ...]
|
||||
await clickElement('Расширенный поиск');
|
||||
```
|
||||
- **Tree nodes**: default click = **select** (highlight row). Use `{ expand: true }` to **expand/collapse**:
|
||||
```js
|
||||
await clickElement('ИСУ ФХД'); // select row
|
||||
await clickElement('ИСУ ФХД', { expand: true }); // expand/collapse
|
||||
```
|
||||
- **Multi-select rows** with `modifier: 'ctrl'` (add to selection) or `modifier: 'shift'` (select range):
|
||||
```js
|
||||
await clickElement('Номенклатура 1'); // select first row
|
||||
await clickElement('Номенклатура 2', { modifier: 'ctrl' }); // add to selection
|
||||
await clickElement('Номенклатура 5', { modifier: 'shift' }); // select range 2..5
|
||||
// Verify selection:
|
||||
const t = await readTable();
|
||||
t.rows.filter(r => r._selected); // rows with _selected: true
|
||||
```
|
||||
- **SpreadsheetDocument cells** (report drill-down): first argument can be `{ row, column }` object to click a cell in a rendered report. Coordinates match `readSpreadsheet()` output:
|
||||
```js
|
||||
const report = await readSpreadsheet();
|
||||
// report.data[0] = { 'К1': 'Материалы строительные', 'К6': '150 000', ... }
|
||||
|
||||
// By data row index + column header name
|
||||
await clickElement({ row: 0, column: 'К6' }, { dblclick: true });
|
||||
|
||||
// By cell value filter (fuzzy match)
|
||||
await clickElement({ row: { 'К1': 'Материалы' }, column: 'К6' }, { dblclick: true });
|
||||
|
||||
// Totals row
|
||||
await clickElement({ row: 'totals', column: 'К6' }, { dblclick: true });
|
||||
```
|
||||
Text search also works as fallback — searches inside spreadsheet iframes:
|
||||
```js
|
||||
await clickElement('150 000', { dblclick: true }); // finds cell by text in report
|
||||
```
|
||||
|
||||
#### `fillFields({ name: value })` → `{ filled, form }`
|
||||
Fill form fields by label (fuzzy match). Auto-detects field type.
|
||||
|
||||
| Value | Field type | Method |
|
||||
|-------|-----------|--------|
|
||||
| `'Конфетпром'` | Reference | Clipboard paste + typeahead |
|
||||
| `'5000'` | Plain text | Clipboard paste |
|
||||
| `'true'` / `'да'` | Checkbox | Toggle |
|
||||
| `'Оплата поставщику'` | Radio | Fuzzy label match |
|
||||
| `''` / `null` | Any (except checkbox/radio) | Clear via Shift+F4 |
|
||||
|
||||
**DCS report filters**: use human-readable label names. Checkbox is auto-enabled:
|
||||
```js
|
||||
await fillFields({
|
||||
'Склад': 'Склад бытовой техники', // auto-enables "Склад" checkbox + fills value
|
||||
'Номенклатура': 'Вентилятор' // same: enables checkbox + fills
|
||||
});
|
||||
```
|
||||
|
||||
Returns `{ filled: [{ field, ok, value, method }], form: {...} }`.
|
||||
Method is one of: `'clear'` | `'toggle'` | `'radio'` | `'paste'` | `'dropdown'` | `'form'` | `'typeahead'`
|
||||
|
||||
#### `selectValue(field, search, opts?)` → form state with `selected`
|
||||
Select a value from reference field via dropdown or selection form. More reliable than `fillFields` for reference fields that need exact selection from a catalog. Pass empty `search` (`''` or `null`) to clear the field (Shift+F4).
|
||||
|
||||
`search` — string for simple search, or `{ field: value }` object for per-field advanced search:
|
||||
```js
|
||||
await selectValue('Организация', 'Конфетпром');
|
||||
// result.selected = { field: 'Организация', search: 'Конфетпром', method: 'dropdown'|'form' }
|
||||
|
||||
// Per-field search (disambiguate by multiple columns):
|
||||
await selectValue('Документ', { 'Номер': '0000-000601', 'Дата': '29.12.2016' }, { type: 'Реализация (акт' });
|
||||
```
|
||||
|
||||
For **composite-type fields** (accepting multiple types), specify `type` to first select the type, then the value:
|
||||
```js
|
||||
await selectValue('Документ', '0000-000601', { type: 'Реализация (акт' });
|
||||
// Clears field → opens type dialog → picks type via Ctrl+F → picks value from selection form
|
||||
// result.selected = { field: 'Документ', search: '0000-000601', type: 'Реализация (акт', method: 'form' }
|
||||
```
|
||||
|
||||
Also supports DCS labels — auto-enables the paired checkbox.
|
||||
|
||||
#### `fillTableRow(fields, opts)` → form state
|
||||
Fill table row cells via Tab navigation. Value is a plain string, `{ value, type }` for composite-type cells, or `''`/`null` to clear (Shift+F4).
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `tab` | Switch to tab before filling |
|
||||
| `add` | Add new row before filling |
|
||||
| `row` | Edit existing row by 0-based index |
|
||||
| `table` | Grid name from `tables[]` (for multi-grid forms) |
|
||||
|
||||
```js
|
||||
// Add new row:
|
||||
await fillTableRow(
|
||||
{ 'Номенклатура': 'Бумага', 'Количество': '10', 'Цена': '100' },
|
||||
{ tab: 'Товары', add: true }
|
||||
);
|
||||
// Edit existing row:
|
||||
await fillTableRow(
|
||||
{ 'Количество': '20' },
|
||||
{ tab: 'Товары', row: 0 }
|
||||
);
|
||||
// Multi-grid form — add row to specific table:
|
||||
await fillTableRow(
|
||||
{ 'Объект': 'БДДС' },
|
||||
{ table: 'Исходящие', add: true }
|
||||
);
|
||||
// Composite-type cell (e.g. SubConto accepting multiple types):
|
||||
await fillTableRow(
|
||||
{ 'СубконтоКт1': { value: 'Голованов', type: 'Физическое лицо' } },
|
||||
{ tab: 'Проводки' }
|
||||
);
|
||||
```
|
||||
|
||||
- Tab-based sequential navigation — field order set by 1C form config
|
||||
- Fuzzy cell match: "Количество" matches "ТоварыКоличество"
|
||||
- Reference cells auto-detected by autocomplete popup
|
||||
|
||||
#### `deleteTableRow(row, { tab?, table? })` → form state
|
||||
Delete row by 0-based index. `table` targets a specific grid on multi-grid forms.
|
||||
|
||||
#### `closeForm({ save? })` → form state with `closed`
|
||||
Close the current form via Escape. Returns form state with `closed: true/false` indicating whether the form actually closed.
|
||||
|
||||
| Argument | Behavior |
|
||||
|----------|----------|
|
||||
| `{ save: false }` | Auto-clicks "Нет" on confirmation |
|
||||
| `{ save: true }` | Auto-clicks "Да" on confirmation |
|
||||
| `{}` (omitted) | Returns `confirmation` field if dialog appears |
|
||||
|
||||
**`closed`** — `true` if the form was closed (form number changed), `false` if it stayed open (e.g. Escape was ignored). Always check this to confirm the form actually closed. After closing, check `formCount` to see how many forms remain.
|
||||
|
||||
Preferred over `clickElement('×')` — close buttons on tabs are ambiguous.
|
||||
|
||||
#### `filterList(text, opts?)` → form state
|
||||
Filter list. Simple mode searches all columns, advanced mode targets a specific field.
|
||||
|
||||
```js
|
||||
await filterList('КП00-000018'); // simple — all columns
|
||||
await filterList('Мишка', { field: 'Наименование' }); // advanced — specific column
|
||||
await filterList('Мишка', { field: 'Наименование', exact: true }); // exact match
|
||||
```
|
||||
|
||||
Works on hierarchical catalogs too (flattens the view).
|
||||
|
||||
#### `unfilterList({ field? })` → form state
|
||||
Clear filters. Without arguments clears all, with `{ field }` clears specific badge.
|
||||
|
||||
### Utility
|
||||
|
||||
#### `screenshot()` → PNG Buffer
|
||||
#### `wait(seconds)` → form state
|
||||
#### `getPage()` → Playwright Page (raw, for advanced scripting)
|
||||
#### `startRecording(path, opts?)` / `stopRecording()` → MP4 video recording (`{ force: true }` to restart if already recording)
|
||||
#### `showCaption(text, opts?)` / `hideCaption()` → text overlay on page
|
||||
#### `showTitleSlide(text, opts?)` / `hideTitleSlide()` → full-screen title card (intro/outro)
|
||||
#### `isRecording()` → boolean
|
||||
#### `setHighlight(on)` / `isHighlightMode()` → auto-highlight mode for video
|
||||
#### `highlight(text)` / `unhighlight()` → manual element highlighting (error lists available elements)
|
||||
#### `addNarration(videoPath, opts?)` → narrated MP4 with TTS voiceover
|
||||
#### `getCaptions()` → caption timestamps from last recording
|
||||
|
||||
See [recording.md](recording.md) for setup (ffmpeg), highlight mode, TTS narration, API details, and examples.
|
||||
If `.v8-project.json` has `ffmpegPath`, pass it to `startRecording({ ffmpegPath })`.
|
||||
If `.v8-project.json` has `tts` config, pass it to `addNarration()` (provider, voice, apiKey).
|
||||
|
||||
## Common patterns
|
||||
|
||||
### Create and save a document
|
||||
|
||||
```js
|
||||
await navigateSection('Продажи');
|
||||
await openCommand('Заказы клиентов');
|
||||
await clickElement('Создать');
|
||||
await fillFields({ 'Организация': 'Конфетпром', 'Контрагент': 'Альфа' });
|
||||
await fillTableRow({ 'Номенклатура': 'Бумага', 'Количество': '10' }, { tab: 'Товары', add: true });
|
||||
await clickElement('Провести и закрыть');
|
||||
```
|
||||
|
||||
### Open item from list
|
||||
|
||||
```js
|
||||
await clickElement('КП00-000227', { dblclick: true });
|
||||
// Always use { dblclick: true } — single click only selects the row
|
||||
```
|
||||
|
||||
### Work with hierarchical lists
|
||||
|
||||
```js
|
||||
await filterList('Конфетпром'); // flatten + search
|
||||
await clickElement('Конфетпром ООО', { dblclick: true }); // open
|
||||
await closeForm();
|
||||
await unfilterList(); // restore hierarchy
|
||||
```
|
||||
|
||||
### Generate and read a report
|
||||
|
||||
```js
|
||||
// Fill report filters using readable labels
|
||||
await fillFields({ 'Склад': 'Основной склад' });
|
||||
await clickElement('Сформировать');
|
||||
await wait(5);
|
||||
const report = await readSpreadsheet();
|
||||
console.log('Title:', report.title);
|
||||
console.log('Data rows:', report.data?.length);
|
||||
```
|
||||
|
||||
### Drill-down report cells
|
||||
|
||||
```js
|
||||
// Generate report
|
||||
await clickElement('Сформировать');
|
||||
await wait(5);
|
||||
const report = await readSpreadsheet();
|
||||
|
||||
// Double-click cell to open drill-down (uses coordinates from readSpreadsheet)
|
||||
await clickElement({ row: 0, column: 'К6' }, { dblclick: true });
|
||||
// Modal dialog "Выбор поля" opens
|
||||
await clickElement('Регистратор');
|
||||
await clickElement('Выбрать');
|
||||
await wait(10);
|
||||
const drilldown = await readSpreadsheet();
|
||||
```
|
||||
|
||||
### Work with multi-grid forms
|
||||
|
||||
Some forms have multiple grids (e.g. "Входящие" and "Исходящие" tables on a single form). Without `table`, buttons like "Добавить" hit the first match and `readTable` reads the first grid — which may not be the one you need.
|
||||
|
||||
**Step 1 — discover tables** via `getFormState()`:
|
||||
```js
|
||||
const form = await getFormState();
|
||||
// form.tables = [
|
||||
// { name: "ДеревоБизнесПроцессов", columns: ["Полный код", "Бизнес-процесс"], rowCount: 21 },
|
||||
// { name: "Входящие", label: "Входящие", columns: ["Объект", "Бизнес-процесс источник", ...], rowCount: 1 },
|
||||
// { name: "Исходящие", label: "Исходящие", columns: ["Объект", "Бизнес-процесс приемник", ...], rowCount: 1 }
|
||||
// ]
|
||||
```
|
||||
|
||||
**Step 2 — use `table` name** in any grid operation:
|
||||
```js
|
||||
// Read specific table
|
||||
const t = await readTable({ table: 'Исходящие' });
|
||||
|
||||
// Add row — fillTableRow with add:true already clicks the right "Добавить" button
|
||||
await fillTableRow({ 'Объект': 'БДДС' }, { table: 'Исходящие', add: true });
|
||||
|
||||
// Or click buttons separately
|
||||
await clickElement('Добавить', { table: 'Входящие' });
|
||||
|
||||
// Delete from specific table
|
||||
await deleteTableRow(0, { table: 'Исходящие' });
|
||||
```
|
||||
|
||||
Table matching accepts both technical name (`tables[].name`) and visual label (`tables[].label`). Label is the group title shown on screen — useful when working from screenshots. Name match takes priority over label match.
|
||||
|
||||
### Keyboard shortcuts
|
||||
|
||||
```js
|
||||
const page = await getPage();
|
||||
await page.keyboard.press('F8'); // example: create new item in focused reference field
|
||||
```
|
||||
|
||||
| Key | Context | Action |
|
||||
|-----|---------|--------|
|
||||
| `F8` | Reference field focused | Create new catalog item |
|
||||
| `Shift+F4` | Any input field focused | Clear field value (auto via `''`/`null` in fillFields/selectValue/fillTableRow) |
|
||||
| `F4` | Reference field focused | Open selection form |
|
||||
| `Alt+F` | List/table form | Open advanced search dialog |
|
||||
|
||||
### Closing forms — which method to use
|
||||
|
||||
| Goal | Method |
|
||||
|------|--------|
|
||||
| Post & close document | `clickElement('Провести и закрыть')` |
|
||||
| Save & close catalog | `clickElement('Записать и закрыть')` |
|
||||
| Close without saving | `closeForm({ save: false })` |
|
||||
| Close and save | `closeForm({ save: true })` |
|
||||
| Close (manual confirm) | `closeForm()` — returns `confirmation` if dialog appears |
|
||||
|
||||
## Exec response format
|
||||
|
||||
```json
|
||||
{ "ok": true, "output": "...console.log output...", "elapsed": 3.2 }
|
||||
```
|
||||
|
||||
On error (auto-screenshot taken):
|
||||
```json
|
||||
{ "ok": false, "error": "Element not found", "output": "...", "screenshot": "error-shot.png", "elapsed": 1.5 }
|
||||
```
|
||||
|
||||
## Avoiding loops
|
||||
|
||||
- **Max 2 attempts per operation.** If an action fails twice with the same approach — stop and report to the user
|
||||
- **Not found = not found.** If `filterList` returns 0 rows or `readTable` is empty after filtering — the item likely doesn't exist in this database. Don't retry the same search 5 times with slight variations
|
||||
- **Try a different approach, not the same one.** Couldn't find via section navigation? Try `navigateLink`. Couldn't find via simple search? Try advanced search with a specific field. But don't repeat the same method
|
||||
- **Report partial results.** If you found the list but not the specific item — say so. Show what IS available instead of silently retrying
|
||||
|
||||
## Important notes
|
||||
|
||||
- **Headed mode** — 1C requires visible browser, no headless
|
||||
- **Startup time** — 1C loads 30-60s on initial connect (built into `start`)
|
||||
- **Fuzzy matching** — all name lookups: exact > startsWith > includes
|
||||
- **Clipboard paste** — all text fields filled via Ctrl+V (triggers 1C events properly)
|
||||
- **Cyrillic in bash** — use `cat <<'SCRIPT' | node $RUN exec -` to avoid escaping issues
|
||||
- **Non-breaking spaces** — 1C uses `\u00a0` instead of regular spaces. All matching is normalized internally
|
||||
- **Section panel display** — `navigateSection()` works with any panel position (side, top) but requires "Picture and text" or "Text" display mode. Icon-only mode is not supported — API cannot read section names from icons alone
|
||||
|
||||
## Regression suites
|
||||
|
||||
When the user asks to cover a 1C solution with automated regression — multi-file test suites with assertions, hooks, tags, retries, Allure/JUnit reports, multi-user process tests — switch to the `test` mode. See [regress.md](regress.md) for authoring discipline, recon flow (metadata + live walkthrough via `exec`), per-application folder layout, ready-to-paste templates, and failure triage. Default to ad-hoc `run`/`exec` for single-script automation — `test` is the specialised mode for project-wide coverage.
|
||||
@@ -0,0 +1,348 @@
|
||||
# Video Recording
|
||||
|
||||
Record browser automation sessions as MP4 video files. Uses CDP `Page.startScreencast` to capture JPEG frames and pipes them to ffmpeg for encoding.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
**ffmpeg** must be installed. Choose один из вариантов:
|
||||
|
||||
### Вариант 1: в проект (рекомендуется)
|
||||
|
||||
Скачать essentials build с https://www.gyan.dev/ffmpeg/builds/, распаковать в `tools/ffmpeg/` проекта:
|
||||
|
||||
```
|
||||
tools/ffmpeg/
|
||||
├── bin/
|
||||
│ ├── ffmpeg.exe ← этот файл ищет startRecording()
|
||||
│ ├── ffplay.exe
|
||||
│ └── ffprobe.exe
|
||||
└── ...
|
||||
```
|
||||
|
||||
Код автоматически найдёт `tools/ffmpeg/bin/ffmpeg.exe` — ничего больше настраивать не нужно.
|
||||
|
||||
### Вариант 2: глобально (один раз на машину)
|
||||
|
||||
Скачать, распаковать в любой каталог (напр. `C:\tools\ffmpeg`), добавить `bin/` в системный PATH.
|
||||
После этого ffmpeg доступен во всех проектах.
|
||||
|
||||
### Вариант 3: через .v8-project.json (общий путь)
|
||||
|
||||
Чтобы не копировать ffmpeg в каждый проект, указать путь в конфиге:
|
||||
|
||||
```json
|
||||
{
|
||||
"ffmpegPath": "C:\\tools\\ffmpeg\\bin\\ffmpeg.exe"
|
||||
}
|
||||
```
|
||||
|
||||
Модель прочитает это поле и передаст в `startRecording({ ffmpegPath })`.
|
||||
|
||||
### Порядок поиска ffmpeg
|
||||
|
||||
1. `opts.ffmpegPath` — явный путь (из `.v8-project.json` или параметра)
|
||||
2. `FFMPEG_PATH` — переменная окружения
|
||||
3. `ffmpeg` — в системном PATH
|
||||
4. `tools/ffmpeg/bin/ffmpeg.exe` — относительно корня проекта
|
||||
|
||||
## API
|
||||
|
||||
### `startRecording(outputPath, opts?)`
|
||||
|
||||
Start recording the browser viewport to an MP4 file.
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `outputPath` | string | required | Output .mp4 file path |
|
||||
| `opts.fps` | number | 25 | Target framerate |
|
||||
| `opts.quality` | number | 80 | JPEG quality (1-100) |
|
||||
| `opts.ffmpegPath` | string | auto | Explicit path to ffmpeg binary |
|
||||
| `opts.speechRate` | number | 70 | Ms per character for smart TTS wait. Increase for slower TTS providers (e.g. 85 for ElevenLabs) |
|
||||
|
||||
- Output directory is created automatically if it doesn't exist
|
||||
- Throws if already recording or browser not connected
|
||||
- Recording auto-stops when `disconnect()` is called
|
||||
|
||||
### `stopRecording()` → `{ file, duration, size, captions }`
|
||||
|
||||
Stop recording and finalize the MP4 file. Saves `.captions.json` next to the video if captions were collected.
|
||||
|
||||
| Return field | Type | Description |
|
||||
|-------------|------|-------------|
|
||||
| `file` | string | Absolute path to the MP4 file |
|
||||
| `duration` | number | Recording duration in seconds |
|
||||
| `size` | number | File size in bytes |
|
||||
| `captions` | number | Number of captions collected during recording |
|
||||
|
||||
### `isRecording()` → boolean
|
||||
|
||||
Check if recording is active.
|
||||
|
||||
### `showCaption(text, opts?)`
|
||||
|
||||
Display a text overlay on the page (visible in recording). Calling again updates the text.
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `text` | string | required | Caption text |
|
||||
| `opts.position` | `'top'` \| `'bottom'` | `'bottom'` | Vertical position |
|
||||
| `opts.fontSize` | number | 24 | Font size in px |
|
||||
| `opts.background` | string | `'rgba(0,0,0,0.7)'` | Background color |
|
||||
| `opts.color` | string | `'#fff'` | Text color |
|
||||
| `opts.speech` | string \| false | - | TTS narration text. Omit = use displayed text, string = custom narration, false = skip narration |
|
||||
| `opts.voice` | string | - | Per-caption voice override (provider-specific voice name/ID). Used by `addNarration` instead of the global voice |
|
||||
|
||||
When `text` is empty but `speech` is a string, the caption is still recorded for TTS (no visible overlay). Useful for narration-only captions (e.g. podcast mode).
|
||||
|
||||
The overlay uses `pointer-events: none` — does not interfere with clicking.
|
||||
|
||||
**Smart TTS wait** (during recording): `showCaption` automatically pauses for the estimated TTS speech duration (default ~70ms per character, min 2s; configurable via `startRecording({ speechRate })`). The next `wait()` call accounts for this — if the explicit pause is shorter than the TTS wait already done, no extra delay is added. If longer, only the remaining difference is waited. This means script authors don't need to calculate TTS timing manually.
|
||||
|
||||
### `hideCaption()`
|
||||
|
||||
Remove the caption overlay.
|
||||
|
||||
### `showTitleSlide(text, opts?)`
|
||||
|
||||
Display a full-screen title slide overlay (gradient background, centered text). Useful for intro/outro frames in video recordings. Calling again updates the content.
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `text` | string | required | Title text (`\n` → line break) |
|
||||
| `opts.subtitle` | string | `''` | Smaller text below the title |
|
||||
| `opts.background` | string | dark gradient | CSS background |
|
||||
| `opts.color` | string | `'#fff'` | Text color |
|
||||
| `opts.fontSize` | number | 36 | Title font size in px |
|
||||
| `opts.speech` | string \| false | - | TTS narration text. String = custom text, `true` = use title text, omit/false = no narration |
|
||||
| `opts.voice` | string | - | Per-caption voice override for `addNarration` |
|
||||
|
||||
The overlay covers the entire viewport with `z-index: 999999` and `pointer-events: none`.
|
||||
|
||||
### `hideTitleSlide()`
|
||||
|
||||
Remove the title slide overlay.
|
||||
|
||||
### `showImage(imagePath, opts?)`
|
||||
|
||||
Display a full-screen image overlay (e.g. presentation slide screenshot). Reads the file, base64-encodes it, and renders as `<img>` in a fixed overlay — captured by CDP screencast automatically.
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `imagePath` | string | required | Path to image file (PNG, JPG, GIF, WebP, SVG) |
|
||||
| `opts.style` | `'blur'` \| `'dark'` \| `'light'` \| `'full'` | `'blur'` | Display style preset |
|
||||
| `opts.background` | string | - | Custom background (overrides preset) |
|
||||
| `opts.shadow` | boolean | preset | Show drop shadow on image |
|
||||
| `opts.speech` | string \| false | - | TTS narration text while image is shown |
|
||||
| `opts.voice` | string | - | Per-caption voice override for `addNarration` |
|
||||
|
||||
**Style presets:**
|
||||
- `blur` — blurred+dimmed copy of the image as background, centered image with shadow
|
||||
- `dark` — dark background (#2a2a2a) with shadow
|
||||
- `light` — white background with shadow
|
||||
- `full` — image fills entire screen (contain, no crop), black background, no shadow
|
||||
|
||||
Images are auto-scaled: small images scale up (min 50% of viewport), large images scale down (max 92%).
|
||||
|
||||
### `hideImage()`
|
||||
|
||||
Remove the image overlay.
|
||||
|
||||
### `setHighlight(on)`
|
||||
|
||||
Enable or disable auto-highlight mode. When enabled, action functions (`navigateSection`, `openCommand`, `clickElement`, `selectValue`, `fillFields`) automatically highlight the target element for 500ms before performing the action.
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `on` | boolean | `true` to enable, `false` to disable |
|
||||
|
||||
**How it works**: each action highlights the element → waits 500ms (viewer reads) → removes highlight → performs the action. This prevents the highlight overlay from interfering with modals, dropdowns, or focus changes caused by the action.
|
||||
|
||||
**Search priority**: form elements (buttons, links, fields, grid rows) are searched first. Sections and commands are used as fallback only if the element is not found in the current form. This avoids false matches (e.g., "ОК" matching section "Покупки" via substring).
|
||||
|
||||
### `isHighlightMode()` → boolean
|
||||
|
||||
Check if auto-highlight mode is active.
|
||||
|
||||
### `highlight(text)`
|
||||
|
||||
Manually highlight a UI element by name (fuzzy match). Places a semi-transparent blue overlay (`rgba(0,100,255,0.25)`) with a border on the element. The overlay tracks element position via `requestAnimationFrame`.
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `text` | string | Element name — button, link, field, group/panel, section, or command |
|
||||
|
||||
- Fuzzy match order: exact → startsWith → includes
|
||||
- Search priority: popup items → commands → **form groups/panels** → form elements (buttons, fields) → sections
|
||||
- Groups are matched by visible title or internal name (e.g., `highlight('Оргструктура')` finds the group panel)
|
||||
- `pointer-events: none` — does not block clicks
|
||||
|
||||
### `unhighlight()`
|
||||
|
||||
Remove the highlight overlay.
|
||||
|
||||
## Example: Record a workflow with highlight, title slide, and captions
|
||||
|
||||
```js
|
||||
await startRecording('recordings/create-order.mp4');
|
||||
|
||||
// Title slide with narration
|
||||
await showTitleSlide('Создание заказа клиента', {
|
||||
subtitle: 'Демонстрация',
|
||||
speech: 'Создание заказа клиента. Демонстрация.'
|
||||
});
|
||||
await wait(1);
|
||||
await hideTitleSlide();
|
||||
|
||||
// Presentation slide (optional)
|
||||
await showImage('slides/overview.png', {
|
||||
speech: 'На этом слайде показана общая схема процесса'
|
||||
});
|
||||
await wait(1);
|
||||
await hideImage();
|
||||
|
||||
setHighlight(true); // enable auto-highlight for all actions
|
||||
|
||||
// Steps: caption → pause → action (highlight is automatic)
|
||||
await showCaption('Шаг 1. Переходим в раздел «Продажи»');
|
||||
await wait(1.5);
|
||||
await navigateSection('Продажи');
|
||||
|
||||
await showCaption('Шаг 2. Открываем заказы клиентов');
|
||||
await wait(1.5);
|
||||
await openCommand('Заказы клиентов');
|
||||
|
||||
await showCaption('Шаг 3. Создаём новый заказ');
|
||||
await wait(1.5);
|
||||
await clickElement('Создать');
|
||||
await wait(2); // wait for form to load
|
||||
|
||||
await showCaption('Шаг 4. Заполняем шапку');
|
||||
await wait(1.5);
|
||||
await fillFields({ 'Организация': 'Конфетпром', 'Контрагент': 'Альфа' });
|
||||
await wait(1);
|
||||
|
||||
await hideCaption();
|
||||
setHighlight(false);
|
||||
const result = await stopRecording();
|
||||
console.log(`Recorded ${result.duration}s, ${(result.size / 1024 / 1024).toFixed(1)} MB`);
|
||||
```
|
||||
|
||||
**Caption timing**: show the caption *before* the action — `showCaption` auto-waits for estimated TTS duration during recording. The subsequent `wait()` is absorbed by the credit system (no double-waiting). Add `wait()` *after* the action only when the next step needs the result to load (e.g., form opening).
|
||||
|
||||
**Highlight timing**: `setHighlight(true)` enables auto-mode — each action function highlights the target for 500ms, then removes the highlight before performing the action. No manual `highlight()`/`unhighlight()` calls needed. Enable after title slide, disable before `stopRecording()`.
|
||||
|
||||
## TTS Narration
|
||||
|
||||
Add voiceover to recorded videos. Captions shown via `showCaption()` are automatically collected during recording and can be synthesized into speech.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **ffmpeg** — same as for video recording (ffprobe must be next to ffmpeg)
|
||||
- **node-edge-tts** — `npm install --prefix tools/tts node-edge-tts` (for Edge TTS provider, free, no API key). Also works if installed globally or at project level — the resolver tries multiple locations automatically
|
||||
|
||||
### Configuration in `.v8-project.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"tts": {
|
||||
"provider": "edge",
|
||||
"voice": "ru-RU-DmitryNeural"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For OpenAI-compatible provider:
|
||||
```json
|
||||
{
|
||||
"tts": {
|
||||
"provider": "openai",
|
||||
"apiKey": "sk-...",
|
||||
"voice": "alloy"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For ElevenLabs:
|
||||
```json
|
||||
{
|
||||
"tts": {
|
||||
"provider": "elevenlabs",
|
||||
"apiKey": "sk_...",
|
||||
"voice": "JBFqnCBsd6RMkjVDRZzb"
|
||||
}
|
||||
}
|
||||
```
|
||||
Note: `voice` is the ElevenLabs voice ID (not a name). Default model: `eleven_multilingual_v2` (supports Russian and other languages).
|
||||
|
||||
### `showCaption()` speech parameter
|
||||
|
||||
The `speech` option controls what text is narrated (vs displayed):
|
||||
|
||||
```js
|
||||
await showCaption('Дт 60.02 — Кт 51'); // narrates the displayed text
|
||||
await showCaption('Дт 60.02 — Кт 51', { speech: 'Проводка: дебет шестьдесят ноль два, кредит пятьдесят один' }); // custom narration
|
||||
await showCaption('Техническая информация', { speech: false }); // no narration for this caption
|
||||
```
|
||||
|
||||
### `addNarration(videoPath, opts?)`
|
||||
|
||||
Generate TTS and merge audio with video. Call after `stopRecording()`.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `videoPath` | `string` | Path to the recorded MP4 file |
|
||||
| `opts.captions` | `Array` | Explicit captions (default: from last recording or `.captions.json`). Each caption may include a `voice` field to override the global voice for that segment |
|
||||
| `opts.provider` | `string` | `'edge'` (default), `'openai'`, or `'elevenlabs'` |
|
||||
| `opts.voice` | `string` | Voice name (provider-specific) |
|
||||
| `opts.apiKey` | `string` | API key (for openai) |
|
||||
| `opts.apiUrl` | `string` | Endpoint (for openai) |
|
||||
| `opts.model` | `string` | Model (for openai, default: `tts-1`) |
|
||||
| `opts.ffmpegPath` | `string` | Path to ffmpeg binary |
|
||||
| `opts.outputPath` | `string` | Output file (default: `video-narrated.mp4`) |
|
||||
|
||||
**Returns:** `{ file, duration, size, captions, warnings? }`
|
||||
|
||||
### `getCaptions()`
|
||||
|
||||
Returns captions from the current or last recording: `Array<{ text, speech, time, voice? }>`.
|
||||
|
||||
### Example: Record and narrate
|
||||
|
||||
```js
|
||||
await startRecording('recordings/demo.mp4');
|
||||
await showCaption('Переходим в раздел Банк и касса');
|
||||
await wait(1.5);
|
||||
await navigateSection('Банк и касса');
|
||||
await showCaption('Открываем банковские выписки');
|
||||
await wait(1.5);
|
||||
await openCommand('Банковские выписки');
|
||||
await hideCaption();
|
||||
const video = await stopRecording();
|
||||
|
||||
// Add narration (reads tts config from .v8-project.json)
|
||||
const narrated = await addNarration(video.file, { voice: 'ru-RU-DmitryNeural' });
|
||||
console.log(`Narrated: ${narrated.file}, ${narrated.duration}s`);
|
||||
```
|
||||
|
||||
### Re-narration
|
||||
|
||||
After recording, a `.captions.json` file is saved next to the video. You can re-narrate with a different voice without re-recording:
|
||||
|
||||
```js
|
||||
const result = await addNarration('recordings/demo.mp4', { voice: 'ru-RU-SvetlanaNeural' });
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| "ffmpeg not found" | Install ffmpeg and ensure it's discoverable (see Prerequisites) |
|
||||
| Recording file is 0 bytes | Check that output path is writable. ffmpeg may have crashed |
|
||||
| Video is choppy | Add `wait()` between steps. Reduce `quality` for faster capture |
|
||||
| "Already recording" | Call `stopRecording()` before starting a new recording |
|
||||
| Recording stops on disconnect | Expected — auto-stop prevents orphaned ffmpeg processes |
|
||||
| "No captions available" | Use `showCaption()` during recording, or pass `opts.captions` |
|
||||
| TTS timeout | Check internet connection. Edge TTS requires network access |
|
||||
| Audio cuts off between captions | Smart TTS wait should handle this automatically. If warnings appear, add longer `wait()` after `showCaption` |
|
||||
@@ -0,0 +1,433 @@
|
||||
# Regression suite authoring
|
||||
|
||||
Use this when the user asks to cover a 1C solution with automated regression tests, build out a test suite, or run an existing suite and analyse failures. For ad-hoc single-script automation, stay with the `run`/`exec` modes from SKILL.md instead.
|
||||
|
||||
The runner is the same `run.mjs`. The mode is `test`:
|
||||
|
||||
```bash
|
||||
node $RUN test [url] <dir|file> [flags]
|
||||
```
|
||||
|
||||
Tests live next to the project they cover (not inside the skill). Convention: `tests/` at the project root, with `_hooks.mjs` and `webtest.config.mjs` at the suite root. Tests are ES modules with `*.test.mjs` suffix.
|
||||
|
||||
## When to choose `test` over `exec`
|
||||
|
||||
| Goal | Mode |
|
||||
|------|------|
|
||||
| Explore a form, prototype a single step, debug one selector | `exec` (interactive session) |
|
||||
| **Walk through a scenario live before committing it as a test** | `exec` first, then `test` |
|
||||
| Reproduce a bug as a failing test before fixing it | `test` |
|
||||
| Cover a feature so future changes are checked automatically | `test` |
|
||||
| Run the project's regression on a new build | `test` |
|
||||
| Generate a screencast walkthrough | `exec` with `startRecording` |
|
||||
|
||||
Don't write a `.test.mjs` for a one-shot user request. Don't drive a regression suite through chained `exec` calls.
|
||||
|
||||
## Before writing tests — recon
|
||||
|
||||
Two layers, in order. Don't skip either.
|
||||
|
||||
### 1. Static recon — metadata
|
||||
|
||||
Never invent identifiers. For every metadata object the user mentions (or that you decide to cover), run the matching info skill first:
|
||||
|
||||
| Object type | Skill |
|
||||
|-------------|-------|
|
||||
| Catalog/document/register attributes, tabular sections | `/meta-info` |
|
||||
| Form layout — fields, buttons, tabs, tables | `/form-info` |
|
||||
| DCS report — fields, parameters, filters | `/skd-info` |
|
||||
| Spreadsheet template areas/parameters | `/mxl-info` |
|
||||
| Role rights / restrictions | `/role-info` |
|
||||
| Subsystem composition / command interface | `/subsystem-info` |
|
||||
|
||||
This gives the real Russian field labels, command names, column headers, table-section names. Without it, fuzzy matching will silently land on the wrong element, or fail with no useful diagnostic.
|
||||
|
||||
If the user names objects you cannot find: stop and ask. Do not guess.
|
||||
|
||||
### 2. Live recon — interactive walkthrough
|
||||
|
||||
For any non-trivial scenario, walk the path live in `exec` mode before writing it down. Metadata tells you what exists; the live walkthrough tells you what actually happens — which button posts the document, which dialog 1C raises, how the form looks after `clickElement('Создать')`, what fields are required, where `wait()` is genuinely needed.
|
||||
|
||||
```bash
|
||||
# Start a session (background).
|
||||
node $RUN start http://localhost:9191/myapp/ru_RU
|
||||
|
||||
# Step the scenario interactively. After each step, inspect.
|
||||
cat <<'EOF' | node $RUN exec -
|
||||
await navigateSection('Склад');
|
||||
const cmds = await getCommands();
|
||||
console.log(cmds);
|
||||
EOF
|
||||
|
||||
cat <<'EOF' | node $RUN exec -
|
||||
await openCommand('Приходная накладная');
|
||||
await clickElement('Создать');
|
||||
const s = await getFormState();
|
||||
console.log(JSON.stringify(s.fields.map(f => ({ name: f.name, label: f.label, required: f.required })), null, 2));
|
||||
console.log('buttons:', s.buttons.map(b => b.name));
|
||||
console.log('tables:', s.tables.map(t => ({ name: t.name, label: t.label, columns: t.columns })));
|
||||
EOF
|
||||
|
||||
# Try the actions you plan to encode. If a step fails, fix and re-try
|
||||
# before transcribing it.
|
||||
cat <<'EOF' | node $RUN exec -
|
||||
await fillFields({ 'Контрагент': 'ООО Север' });
|
||||
await fillTableRow({ 'Номенклатура': 'Товар 01', 'Количество': '5' },
|
||||
{ table: 'Товары', add: true });
|
||||
await clickElement('Провести и закрыть');
|
||||
console.log(JSON.stringify(await getFormState()));
|
||||
EOF
|
||||
|
||||
# When done, stop the session (or leave it for the next test you write).
|
||||
node $RUN stop
|
||||
```
|
||||
|
||||
What to record from the walkthrough into the test:
|
||||
- Exact button names (`'Провести и закрыть'`, not `'Сохранить'`).
|
||||
- Field labels as 1C renders them (with possible non-breaking spaces — `fillFields` normalises, but be exact).
|
||||
- Table section names from `getFormState().tables[].name`/`label` for multi-grid forms.
|
||||
- Required `wait()` durations — only where a real async event happens (report generation, server-side calculation). Default actions await internally.
|
||||
- The shape of `getFormState()` after each action — gives you the right `assert.equal(...)` paths.
|
||||
|
||||
After this, transcribe the working sequence into `*.test.mjs`, wrap each chunk in `step('...', async () => { ... })`, add assertions for the invariants you saw. Run the file once with `node $RUN test path/to/file.test.mjs` to confirm.
|
||||
|
||||
When live recon is overkill: trivial reads (`navigateSection` + `readTable` + assert non-empty), or scenarios you've already proven once in this session. When it's essential: anything with confirmation dialogs, posting/cancellation flows, reports with custom filters, multi-grid forms, or user-customised forms you've never seen.
|
||||
|
||||
## Suite layout
|
||||
|
||||
**Each application gets its own subfolder under `tests/`.** A single repo may host several independent suites side by side — they must not share `_hooks.mjs` or `webtest.config.mjs`, because each suite restores a different DB, publishes to a different URL, and ships its own test data.
|
||||
|
||||
```
|
||||
tests/
|
||||
web-test/ # engine self-tests (reserved if our repo layout)
|
||||
<app-name>/ # application regression — one per solution
|
||||
_hooks.mjs
|
||||
webtest.config.mjs
|
||||
01-login/
|
||||
02-counterparties/
|
||||
...
|
||||
<another-app>/ # second solution, fully isolated
|
||||
_hooks.mjs
|
||||
...
|
||||
```
|
||||
|
||||
`<app-name>` is the project/extension slug (`acc-payroll`, `erp-customisation`, etc.). Pick something stable and pass it on the CLI:
|
||||
|
||||
```bash
|
||||
node $RUN test tests/<app-name>/
|
||||
```
|
||||
|
||||
Inside the application subfolder, organize by **feature**, not by metadata kind. Numeric prefixes on both folder and file enforce run order (discovery is alphabetic by full path).
|
||||
|
||||
```
|
||||
tests/<app-name>/
|
||||
_hooks.mjs # stand prep + cross-cutting hooks (optional)
|
||||
webtest.config.mjs # url, contexts, defaults (optional)
|
||||
01-login/
|
||||
01-open-base.test.mjs
|
||||
02-section-navigation.test.mjs
|
||||
02-counterparties/
|
||||
01-create.test.mjs
|
||||
02-edit-phone.test.mjs
|
||||
03-goods-receipt/
|
||||
01-fill.test.mjs
|
||||
02-post.test.mjs
|
||||
03-unpost.test.mjs
|
||||
04-balance-report/
|
||||
01-generate.test.mjs
|
||||
02-warehouse-filter.test.mjs
|
||||
05-approval-process/
|
||||
01-end-to-end.test.mjs # multi-user
|
||||
```
|
||||
|
||||
Per-folder `_hooks.mjs` / `webtest.config.mjs` inside the application subfolder are NOT supported. Only the application-root copies are loaded.
|
||||
|
||||
## Test file anatomy
|
||||
|
||||
```js
|
||||
export const name = 'Создание контрагента'; // required
|
||||
export const tags = ['catalog', 'create']; // optional, used for filtering + Allure
|
||||
export const timeout = 60000; // optional, default 30000
|
||||
// export const skip = 'pending fix #123'; // optional: true | string
|
||||
// export const only = true; // debug-only — never commit
|
||||
// export const context = 'manager'; // optional, single non-default context
|
||||
// export const contexts = ['clerk', 'manager']; // optional, multi-user test
|
||||
// export const severity = 'critical'; // optional, overrides config severity
|
||||
|
||||
export async function setup(ctx) {
|
||||
// per-test prep — runs before default. Skip if not needed.
|
||||
}
|
||||
|
||||
export async function teardown(ctx) {
|
||||
// per-test cleanup — runs after default, always (even on failure).
|
||||
}
|
||||
|
||||
export default async function(ctx) {
|
||||
const { navigateSection, openCommand, clickElement, fillFields,
|
||||
readTable, closeForm, getFormState,
|
||||
assert, step, log } = ctx;
|
||||
|
||||
await step('Открыть список контрагентов', async () => {
|
||||
await navigateSection('Продажи');
|
||||
await openCommand('Контрагенты');
|
||||
});
|
||||
|
||||
await step('Создать нового контрагента', async () => {
|
||||
await clickElement('Создать');
|
||||
await fillFields({ 'Наименование': 'Тест ' + Date.now() });
|
||||
await clickElement('Записать и закрыть');
|
||||
});
|
||||
|
||||
await step('Убедиться, что элемент появился в списке', async () => {
|
||||
const t = await readTable();
|
||||
assert.tableHasRow(t, r => r['Наименование']?.startsWith('Тест '));
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
The runner injects every `browser.mjs` export into `ctx` plus `assert`, `step`, `log`, `testInfo`, `testResult` (afterEach only). For multi-context tests, each context name is its own scoped namespace (`ctx.clerk.clickElement(...)` etc.) — `step`/`assert` stay top-level.
|
||||
|
||||
**Step names — in Russian, descriptive.** Step labels surface in the console output, in JSON/JUnit, and as Allure step nodes. Russian-speaking QA reads them. Use a full action phrase (`'Создать нового контрагента'`, `'Проверить наличие документа в списке'`), not a tag (`'create'`, `'verify'`) and not a transliteration. Same applies to `export const name` and `displayName` in `webtest.config.mjs`.
|
||||
|
||||
## webtest.config.mjs
|
||||
|
||||
```js
|
||||
export default {
|
||||
// Single-context: just url.
|
||||
url: 'http://localhost:9191/myapp/ru_RU',
|
||||
|
||||
// OR multi-context: named contexts. Each test picks via `context`/`contexts` exports.
|
||||
// contexts: {
|
||||
// clerk: { url: 'http://localhost:9191/myapp-clerk/ru_RU', displayName: 'Кладовщик' },
|
||||
// manager: { url: 'http://localhost:9191/myapp-manager/ru_RU', displayName: 'Менеджер' },
|
||||
// },
|
||||
// defaultContext: 'clerk',
|
||||
|
||||
timeout: 30000,
|
||||
retries: 0,
|
||||
screenshot: 'on-failure',
|
||||
record: false,
|
||||
|
||||
// Severity → tags mapping for Allure. Each tag at most one bucket.
|
||||
severity: {
|
||||
critical: ['smoke', 'crud'],
|
||||
minor: ['recording'],
|
||||
},
|
||||
defaultSeverity: 'normal',
|
||||
};
|
||||
```
|
||||
|
||||
CLI flags override config. Recommend latin context IDs + Russian `displayName` for video badges.
|
||||
|
||||
## _hooks.mjs
|
||||
|
||||
Two layers. Infra hooks run without a browser; testlevel hooks receive `ctx`.
|
||||
|
||||
```js
|
||||
import { execSync } from 'child_process';
|
||||
|
||||
// Infra — runs once around the whole suite.
|
||||
export async function prepare({ hookArgs, log, config }) {
|
||||
// Restore DB, publish to Apache, build EPF, etc.
|
||||
// hookArgs = everything after `--` on the CLI. Parse yourself.
|
||||
if (hookArgs.includes('--rebuild-stand')) { /* full rebuild */ }
|
||||
// Use idempotent hash-locks to skip work on warm starts.
|
||||
}
|
||||
|
||||
export async function cleanup({ log, config }) {
|
||||
// Tear down or leave the stand running. Choose per project.
|
||||
}
|
||||
|
||||
// Testlevel — runs with browser ctx.
|
||||
export async function beforeAll(ctx) { /* once after first context opens */ }
|
||||
export async function afterAll(ctx) { /* once before final teardown */ }
|
||||
export async function beforeEach(ctx) { /* ctx.testInfo is set */ }
|
||||
export async function afterEach(ctx) { /* ctx.testResult is set */ }
|
||||
|
||||
// Per-context — runs whenever a context is created/closed.
|
||||
export async function afterOpenContext(ctx, name, spec) { /* spec = config.contexts[name] */ }
|
||||
export async function beforeCloseContext(ctx, name, spec) { }
|
||||
```
|
||||
|
||||
Built-in state reset (`dismissPendingErrors` + close all forms) runs after `afterEach` automatically. Don't reimplement it.
|
||||
|
||||
**Where to put data setup:**
|
||||
- DB restore, publication, EPF build → `prepare()`. Make it idempotent (hash-locks on inputs — config sources, EPF spec, DB dump) so warm starts skip everything but a liveness probe.
|
||||
- Test-specific seed data (the document this test will edit, the counterparty it expects) → per-test `setup`.
|
||||
- Shared session-wide warmup → `beforeAll`.
|
||||
|
||||
## Ready-to-paste patterns
|
||||
|
||||
### Catalog full cycle
|
||||
|
||||
```js
|
||||
await step('Создать контрагента', async () => {
|
||||
await navigateSection('Продажи');
|
||||
await openCommand('Контрагенты');
|
||||
await clickElement('Создать');
|
||||
await fillFields({ 'Наименование': 'ТД Тест', 'ИНН': '7707083893' });
|
||||
await clickElement('Записать и закрыть');
|
||||
});
|
||||
await step('Проверить наличие в списке', async () => {
|
||||
const t = await readTable({ maxRows: 50 });
|
||||
assert.tableHasRow(t, { 'Наименование': 'ТД Тест' });
|
||||
});
|
||||
await step('Удалить контрагента и подтвердить удаление', async () => {
|
||||
await clickElement('ТД Тест');
|
||||
const page = await getPage();
|
||||
await page.keyboard.press('Delete');
|
||||
await clickElement('Да');
|
||||
});
|
||||
```
|
||||
|
||||
### Document create + post
|
||||
|
||||
```js
|
||||
const marker = 'Тест-' + Date.now();
|
||||
await openCommand('Приходная накладная');
|
||||
await clickElement('Создать');
|
||||
await fillFields({ 'Контрагент': 'ООО Север', 'Комментарий': marker });
|
||||
await fillTableRow(
|
||||
{ 'Номенклатура': 'Товар 01', 'Количество': '5', 'Цена': '100' },
|
||||
{ table: 'Товары', add: true }
|
||||
);
|
||||
await clickElement('Провести и закрыть');
|
||||
// Verify: re-open list, filter or scan, assert by `marker`.
|
||||
```
|
||||
|
||||
Use a unique marker (`Date.now()` or random suffix) so re-runs don't collide. Identify your own row by it, not by position or natural keys that may already exist in the DB.
|
||||
|
||||
### DCS report
|
||||
|
||||
```js
|
||||
await openCommand('Остатки товаров');
|
||||
// Reset user settings — 1C persists them between sessions.
|
||||
await clickElement('Ещё');
|
||||
await clickElement('Установить стандартные настройки');
|
||||
|
||||
await selectValue('Номенклатура', 'Товар 02'); // auto-enables the filter checkbox
|
||||
await clickElement('Сформировать');
|
||||
await wait(3);
|
||||
const r = await readSpreadsheet();
|
||||
assert.deepEqual(r.headers, ['Номенклатура', 'Количество', 'Сумма']);
|
||||
assert.ok(r.data.length >= 1);
|
||||
assert.ok(r.totals?.['Сумма']);
|
||||
```
|
||||
|
||||
### Multi-user process
|
||||
|
||||
```js
|
||||
export const contexts = ['clerk', 'manager'];
|
||||
|
||||
export default async function({ clerk, manager, step, assert }) {
|
||||
await step('Кладовщик создаёт накладную', async () => {
|
||||
await clerk.navigateSection('Склад');
|
||||
await clerk.openCommand('Приходные накладные');
|
||||
await clerk.clickElement('Создать');
|
||||
await clerk.fillFields({ 'Контрагент': 'ООО Север' });
|
||||
await clerk.clickElement('Записать');
|
||||
});
|
||||
await step('Менеджер утверждает накладную', async () => {
|
||||
await manager.navigateSection('Согласование');
|
||||
await manager.openCommand('На утверждении');
|
||||
await manager.clickElement('ООО Север', { dblclick: true });
|
||||
await manager.clickElement('Утвердить');
|
||||
});
|
||||
await step('Кладовщик видит новый статус', async () => {
|
||||
const s = await clerk.getFormState();
|
||||
assert.equal(s.fields.find(f => f.name === 'Статус')?.value, 'Утверждён');
|
||||
});
|
||||
await step('Освободить сессию кладовщика', async () => {
|
||||
await manager.closeContext('clerk'); // free a 1C license for the next test
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
License caveat: stock 1C allows ~2 web sessions concurrently. Close contexts you no longer need before the next multi-user test starts.
|
||||
|
||||
### Failing-test repro
|
||||
|
||||
```js
|
||||
export const name = 'Bug #123: накладная без контрагента не должна проводиться';
|
||||
export const tags = ['bug', 'validation'];
|
||||
|
||||
export default async function({ openCommand, clickElement, getFormState, assert, step }) {
|
||||
await openCommand('Приходные накладные');
|
||||
await clickElement('Создать');
|
||||
await clickElement('Провести');
|
||||
const s = await getFormState();
|
||||
assert.ok(s.errorModal || s.fields.find(f => f.name === 'Контрагент')?.required,
|
||||
'Должна быть ошибка валидации или поле помечено обязательным');
|
||||
}
|
||||
```
|
||||
|
||||
Write it red first, hand it to the user, fix the underlying issue, re-run green.
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
node $RUN test tests/<app-name>/ # full app suite
|
||||
node $RUN test tests/<app-name>/03-goods-receipt/ # one feature folder
|
||||
node $RUN test tests/<app-name>/02-counterparties/01-create.test.mjs # one file
|
||||
node $RUN test tests/<app-name>/ --tags=smoke # by tag (intersection)
|
||||
node $RUN test tests/<app-name>/ --grep='накладн' # by name regex
|
||||
node $RUN test tests/<app-name>/ --bail --retry=1 # stop on first fail, allow 1 retry
|
||||
node $RUN test tests/<app-name>/ --report=allure-results --format=allure --report-dir=allure-results
|
||||
node $RUN test tests/<app-name>/ -- --rebuild-stand # everything after `--` goes to hooks
|
||||
```
|
||||
|
||||
Default report is JSON when `--report=…` is given. Allure needs `--format=allure` + a directory. JUnit similarly with `--format=junit`.
|
||||
|
||||
### Allure static config — `_allure/` directory
|
||||
|
||||
The runner copies `<testDir>/_allure/` into the report directory before generating Allure output. Standard Allure convention applies — three files are typically used:
|
||||
|
||||
- **`categories.json`** — failure classification. Always emit this when setting up a suite, with 1C-specific patterns: license pool exhaustion (`Не обнаружено свободной лицензии`), 1C application errors (`ВызватьИсключение|Произошла ошибка|…`), navigation/element lookup misses, runner timeouts, assertion failures.
|
||||
- **`environment.properties`** — `key=value` lines for the Environment widget. Useful when the suite runs across builds/branches (URL, 1C platform version, git branch, configuration version). Often emitted dynamically by `prepare()` rather than committed as a static file.
|
||||
- **`executor.json`** — CI metadata (Jenkins URL, GitHub run ID, etc.). Only relevant when the suite runs on a CI server; for local runs, skip it.
|
||||
|
||||
Discovery skips the underscored directory, so it never collides with tests.
|
||||
|
||||
## Severity guidance
|
||||
|
||||
When the user doesn't dictate, default to:
|
||||
|
||||
| Test kind | Severity |
|
||||
|-----------|----------|
|
||||
| Login + section navigation, basic CRUD on covered entities | `critical` (also tag `smoke`) |
|
||||
| Documents posting, report generation, end-to-end processes | `critical` |
|
||||
| Field-level edge cases, formatting, optional flows | `normal` |
|
||||
| Cosmetic / recording / non-functional | `minor` |
|
||||
| Reserved for show-stopper protections | `blocker` (use sparingly) |
|
||||
|
||||
Don't promote everything to `critical` — it loses signal in the Allure dashboard.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- **Sleeps as a substitute for assertions.** `wait(5)` after `openCommand` is fine; `wait(30)` because something flakes is a bug — find what state you can wait on with `getFormState` instead.
|
||||
- **Retry as a substitute for understanding.** "Not found" twice means the data isn't there or the label is wrong. Don't loop.
|
||||
- **Raw DOM via `getPage().$$(...)`.** Use `getFormState`, `readTable`, `readSpreadsheet`. Raw selectors break across 1C platform versions.
|
||||
- **`clickElement('×')` or `clickElement('Закрыть')`** to dismiss a form. Use `closeForm({ save: true|false })` — handles confirmation correctly.
|
||||
- **Position-based row identification** (`rows[0]`) when the DB has shared seed data. Filter by unique marker or label instead.
|
||||
- **Skipping recon** because "I know what this catalog looks like." You don't — the project's customisation almost certainly differs from a stock config.
|
||||
- **`tags: ['smoke']` on a 90-second test.** Smoke means fast.
|
||||
- **Hand-writing reset code** in `afterEach`. The runner already closes forms and dismisses errors.
|
||||
- **Cross-test state assumptions.** Each test must start from desktop and seed its own data. Order-of-execution coupling is a regression-suite trap.
|
||||
|
||||
## After a run — failure triage
|
||||
|
||||
1. Scan the JSON or Allure summary for `failed`.
|
||||
2. For each failure, read `error.message` + `error.step` + screenshot (saved next to the report).
|
||||
3. If `error.onecError.stack` is present — it's a 1C exception, look at the platform trace.
|
||||
4. Classify:
|
||||
- **Test bug** — selector wrong, expectation wrong, race with no anchor → fix the test.
|
||||
- **Application bug** — actual misbehaviour reproduced → report to the user with the failing step name and the platform stack.
|
||||
- **Stand flake** — Apache timeout, login form not loading, license shortage → fix the hook idempotency or session-cleanup logic, not the test.
|
||||
5. After fixes, re-run only the affected files (`node $RUN test tests/03-goods-receipt/`) before the full suite.
|
||||
|
||||
Report back to the user with the classification, not raw failure dumps.
|
||||
|
||||
## Reference
|
||||
|
||||
- Browser API: [SKILL.md](SKILL.md)
|
||||
- Video and narration: [recording.md](recording.md)
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
+59
@@ -0,0 +1,59 @@
|
||||
{
|
||||
"name": "1c-web-test",
|
||||
"version": "0.2.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "1c-web-test",
|
||||
"version": "0.2.0",
|
||||
"dependencies": {
|
||||
"playwright": "^1.50.0"
|
||||
}
|
||||
},
|
||||
"node_modules/fsevents": {
|
||||
"version": "2.3.2",
|
||||
"resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
|
||||
"integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
|
||||
"hasInstallScript": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"darwin"
|
||||
],
|
||||
"engines": {
|
||||
"node": "^8.16.0 || ^10.6.0 || >=11.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/playwright": {
|
||||
"version": "1.58.2",
|
||||
"resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.2.tgz",
|
||||
"integrity": "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==",
|
||||
"license": "Apache-2.0",
|
||||
"dependencies": {
|
||||
"playwright-core": "1.58.2"
|
||||
},
|
||||
"bin": {
|
||||
"playwright": "cli.js"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
},
|
||||
"optionalDependencies": {
|
||||
"fsevents": "2.3.2"
|
||||
}
|
||||
},
|
||||
"node_modules/playwright-core": {
|
||||
"version": "1.58.2",
|
||||
"resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.58.2.tgz",
|
||||
"integrity": "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==",
|
||||
"license": "Apache-2.0",
|
||||
"bin": {
|
||||
"playwright-core": "cli.js"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"name": "1c-web-test",
|
||||
"version": "0.2.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"description": "Browser automation engine for 1C web client (Playwright)",
|
||||
"dependencies": {
|
||||
"playwright": "^1.50.0"
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user