mirror of
https://github.com/Nikolay-Shirokov/cc-1c-skills.git
synced 2026-08-06 03:30:21 +03:00
docs(web-test): пользовательский гайд регресса + skill-инструкция regress.md
- docs/web-test-regression-guide.md — пользовательские сценарии работы с моделью для покрытия прикладного решения регрессом (русский, по аналогии с web-test-recording-guide.md): структура tests/<app-name>/, диалоги с моделью, пример организации покрытия, отчёты Allure + categories.json. - .claude/skills/web-test/regress.md — инструкция модели по написанию регрессионного набора: разведка (метаданные + живой проход через exec), layout по фичам, готовые шаблоны (CRUD/document/DCS/multi-user/repro), severity, anti-patterns, failure triage, _allure/ конвенция. - SKILL.md — указатель на regress.md в конце файла (рядом с recording). - docs/web-test-runner-spec.md → upload/ (был внутренним планом разработки, не пользовательской документацией). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Nick Shirokov
co-authored by
Claude Opus 4.7
Claude Opus 4.7
parent
b992cd11c5
commit
f4748d76af
@@ -529,3 +529,7 @@ On error (auto-screenshot taken):
|
||||
- **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,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)
|
||||
@@ -0,0 +1,391 @@
|
||||
# Регрессионное тестирование прикладного решения
|
||||
|
||||
Навык `/web-test` умеет не только разово выполнить сценарий в браузере, но и сопровождать прикладное решение полноценным набором автотестов: каждый тест — отдельный файл, с шагами, проверками, тегами, отчётом и видеозаписью падений. После каждой правки конфигурации модель прогоняет весь набор и показывает, что ожидаемо ведёт себя как раньше, а что сломалось.
|
||||
|
||||
```
|
||||
правка конфигурации → загрузка → обновление → публикация → прогон тестов → отчёт
|
||||
```
|
||||
|
||||
Это про прикладное решение в целом, не про разовую проверку одной формы. Для разовых сценариев («открой накладную, проверь сумму») по-прежнему удобнее интерактивный режим из [web-test-guide.md](web-test-guide.md).
|
||||
|
||||
## Предусловия
|
||||
|
||||
- База опубликована через Apache (`/web-publish`).
|
||||
- Установлен Node.js 18+, зависимости подняты: `cd .claude/skills/web-test/scripts && npm install`.
|
||||
- ffmpeg — нужен только если хотите видеозапись прогона как доказательство падения. Без него падения фиксируются скриншотами. Установка описана в [web-test-recording-guide.md](web-test-recording-guide.md).
|
||||
|
||||
## Как это устроено
|
||||
|
||||
Набор тестов живёт в каталоге `tests/` вашего проекта. Каждое прикладное решение — отдельная подпапка. Внутри подпапки:
|
||||
|
||||
- `_hooks.mjs` — подготовка стенда (восстановление базы, публикация) и общая очистка после прогона. Необязателен.
|
||||
- `webtest.config.mjs` — адрес базы и набор пользователей (например, кладовщик и менеджер для процессов согласования). Необязателен — если в проекте один пользователь и один URL, можно обойтись без него.
|
||||
- Сами тесты — файлы `*.test.mjs`, сгруппированные по функциональным папкам.
|
||||
|
||||
```
|
||||
tests/
|
||||
моя-конфигурация/
|
||||
_hooks.mjs
|
||||
webtest.config.mjs
|
||||
01-вход/
|
||||
01-открытие-базы.test.mjs
|
||||
02-контрагенты/
|
||||
01-создание.test.mjs
|
||||
02-правка-телефона.test.mjs
|
||||
03-поступление-товаров/
|
||||
01-оформление.test.mjs
|
||||
02-проведение.test.mjs
|
||||
04-отчёт-остатки/
|
||||
01-формирование.test.mjs
|
||||
05-согласование/
|
||||
01-полный-цикл.test.mjs
|
||||
```
|
||||
|
||||
Порядок выполнения — по алфавиту, поэтому удобно префиксовать папки и файлы номерами. Это даёт предсказуемый сценарий: сначала вход, потом справочники, потом документы, потом отчёты, в конце — процессы с несколькими пользователями.
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
Самый короткий путь от нуля до зелёного теста — попросить модель пройти ваш сценарий руками и зафиксировать его как тест:
|
||||
|
||||
```
|
||||
> Покрой регрессом справочник Контрагенты в моей конфигурации.
|
||||
> Нужны проверки: создание, правка телефона, удаление.
|
||||
```
|
||||
|
||||
Что сделает модель:
|
||||
|
||||
1. Соберёт информацию о справочнике через `/meta-info` и `/form-info` — посмотрит реквизиты и форму элемента, чтобы знать правильные имена полей.
|
||||
2. Подключится к опубликованной базе в интерактивном режиме и **руками пройдёт** каждый сценарий — создание, правка, удаление. Это нужно, чтобы зафиксировать настоящие имена кнопок, увидеть, какие диалоги показывает 1С, понять, требуется ли подтверждение сохранения.
|
||||
3. Зафиксирует пройденный сценарий как файл `tests/<ваша-конфигурация>/02-контрагенты/01-создание.test.mjs`.
|
||||
4. Запустит его и покажет результат.
|
||||
|
||||
При следующих прогонах ничего этого делать не нужно — модель просто запустит готовый набор.
|
||||
|
||||
## Сценарии работы с моделью
|
||||
|
||||
### Покрытие регрессом доработанного объекта
|
||||
|
||||
```
|
||||
> Я добавил в справочник Номенклатура реквизит "Цена" и "Активен".
|
||||
> Покрой это регрессом — создание, редактирование, фильтрация по активности
|
||||
```
|
||||
|
||||
Модель:
|
||||
- посмотрит структуру справочника и формы (через `/meta-info`, `/form-info`);
|
||||
- интерактивно проверит, как ведут себя новые поля в браузере;
|
||||
- сгенерирует 2-3 тестовых файла под папкой `02-номенклатура/`;
|
||||
- прогонит — покажет, что зелёное, что красное.
|
||||
|
||||
### Тест процесса с несколькими пользователями
|
||||
|
||||
```
|
||||
> Сделай тест для процесса согласования приходных накладных.
|
||||
> Кладовщик создаёт накладную, менеджер утверждает,
|
||||
> кладовщик видит обновлённый статус
|
||||
```
|
||||
|
||||
Модель настроит в `webtest.config.mjs` двух пользователей (с разными URL базы — например, `app-clerk` и `app-manager`), напишет тест, который оркестрирует переключение между ними, и положит его в `05-согласование/`.
|
||||
|
||||
```js
|
||||
export const contexts = ['кладовщик', 'менеджер'];
|
||||
|
||||
export default async function({ кладовщик, менеджер, step, assert }) {
|
||||
await step('Кладовщик создаёт накладную', async () => {
|
||||
await кладовщик.navigateSection('Склад');
|
||||
await кладовщик.openCommand('Приходные накладные');
|
||||
await кладовщик.clickElement('Создать');
|
||||
// ...
|
||||
});
|
||||
await step('Менеджер утверждает', async () => {
|
||||
await менеджер.navigateSection('Согласование');
|
||||
// ...
|
||||
});
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Учтите ограничение по лицензиям 1С: каждый одновременно открытый пользователь — это занятая клиентская лицензия. Если в наборе много многопользовательских тестов, а на стенде лицензий впритык, прогоны начнут спотыкаться на «свободных лицензий не осталось». Модель освобождает сессии между тестами автоматически (закрывает контексты после процессного теста), но если стенд ограничен — закладывайте это в планирование набора: один-два многопользовательских сценария вместо десяти.
|
||||
|
||||
### Воспроизведение ошибки тестом
|
||||
|
||||
```
|
||||
> При проведении накладной без заполненного контрагента у нас не появляется
|
||||
> ошибка валидации, документ просто проводится с пустым контрагентом — это баг.
|
||||
> Зафиксируй это падающим тестом
|
||||
```
|
||||
|
||||
Модель воспроизведёт сценарий, напишет тест с проверкой «должна быть ошибка», получит красный — потом, когда вы поправите конфигурацию и попросите перепрогнать, тест станет зелёным. Это документирует ожидаемое поведение в виде кода.
|
||||
|
||||
### Прогон регресса после изменений
|
||||
|
||||
```
|
||||
> Я обновил расширение, накатил в базу. Прогони регресс
|
||||
```
|
||||
|
||||
Модель запустит весь набор, дождётся завершения и расскажет:
|
||||
- сколько тестов прошло, сколько упало, сколько пропущено;
|
||||
- по каждому упавшему — что именно сломалось (название шага, сообщение об ошибке, ссылка на скриншот);
|
||||
- классифицирует падения: это ошибка в самом тесте (нужно поправить тест), ошибка в приложении (баг, который вы внесли изменением), или нестабильность стенда (Apache не ответил вовремя, лицензия не освободилась).
|
||||
|
||||
```
|
||||
> Прогони только тесты по контрагентам с подробным отчётом
|
||||
```
|
||||
|
||||
Запустит подмножество — фильтр по тегу или папке, с записью JSON-отчёта.
|
||||
|
||||
### Подготовка автономного стенда
|
||||
|
||||
Если вы хотите, чтобы регресс можно было запустить «с нуля» — даже на чистой машине без подготовленной базы, — модель настроит автоматическую подготовку стенда:
|
||||
|
||||
```
|
||||
> Сделай, чтобы перед прогоном тестов база восстанавливалась из эталона,
|
||||
> а после прогона публикация снималась
|
||||
```
|
||||
|
||||
Это пишется один раз в файле `_hooks.mjs`: при запуске тестов запускается подготовка (через навыки `/db-create`, `/db-load-xml`, `/web-publish`), а после — очистка. Внутри предусмотрено кэширование: если ничего не менялось со прошлого прогона, повторная подготовка занимает доли секунды.
|
||||
|
||||
## Пример организации покрытия
|
||||
|
||||
Допустим, у нас условное прикладное решение «Учёт поступлений товаров» — справочники контрагентов и номенклатуры, документ приходной накладной, отчёт остатков, процесс согласования с двумя пользователями. Логично организовать набор так:
|
||||
|
||||
```
|
||||
tests/учёт-поступлений/
|
||||
_hooks.mjs # подготовка: восстановление базы + публикация
|
||||
webtest.config.mjs # URL базы, контексты кладовщика и менеджера
|
||||
01-вход/
|
||||
01-открытие-базы.test.mjs # базовая работоспособность: вход проходит, разделы видны
|
||||
02-навигация-по-разделам.test.mjs # обход всех разделов конфигурации
|
||||
02-контрагенты/
|
||||
01-создание.test.mjs # создание, проверка появления в списке
|
||||
02-редактирование.test.mjs # правка реквизита, проверка сохранения
|
||||
03-удаление.test.mjs # удаление с подтверждением
|
||||
03-номенклатура/
|
||||
01-создание.test.mjs
|
||||
02-фильтр-по-активности.test.mjs # быстрая фильтрация списка
|
||||
04-поступление-товаров/
|
||||
01-оформление.test.mjs # заполнение шапки и табличной части
|
||||
02-проведение.test.mjs # проведение документа, проверка движений
|
||||
03-отмена-проведения.test.mjs
|
||||
04-валидация-обязательных.test.mjs # негативный тест: пустой контрагент → ошибка
|
||||
05-отчёт-остатки/
|
||||
01-формирование.test.mjs
|
||||
02-отбор-по-складу.test.mjs
|
||||
03-расшифровка.test.mjs # переход из ячейки отчёта в исходный документ
|
||||
06-согласование/
|
||||
01-полный-цикл.test.mjs # многопользовательский тест
|
||||
```
|
||||
|
||||
Принципы:
|
||||
|
||||
- **Папки — по бизнес-функции**, не по типу метаданных. Лучше `04-поступление-товаров/` (что делает пользователь), чем `документы/` (что лежит в дереве конфигурации).
|
||||
- **Цифровые префиксы** — на папке и на файле. Гарантируют, что сначала отработают базовые проверки (вход, справочники), потом сложные (документы, отчёты, процессы). При падении базы остальное и так не пройдёт — нет смысла занимать стенд получасом.
|
||||
- **Один файл — одна логически связанная история.** Не «всё про контрагентов в одном файле», а «отдельно создание, отдельно правка, отдельно удаление». Когда падает — сразу видно, какой именно сценарий сломан.
|
||||
- **Негативные тесты тоже есть.** «Документ без контрагента не проводится» — такой же важный регресс, как и позитивный сценарий, особенно после правок в обработчиках проверки заполнения.
|
||||
- **Процессные тесты — в конце.** Они самые хрупкие (зависят от двух сессий, лицензий, синхронизации) и самые длинные. Если упадут — у вас уже есть данные от предыдущих тестов.
|
||||
|
||||
## Анатомия одного теста
|
||||
|
||||
Пользователь, как правило, тест не пишет — генерирует модель. Но прочитать и поправить полезно уметь. Стандартный файл выглядит так:
|
||||
|
||||
```js
|
||||
export const name = 'Создание контрагента';
|
||||
export const tags = ['контрагенты', 'базовая-проверка'];
|
||||
export const timeout = 60000;
|
||||
|
||||
export default async function({
|
||||
navigateSection, openCommand, clickElement, fillFields,
|
||||
readTable, closeForm, assert, step
|
||||
}) {
|
||||
await step('Открыть список контрагентов', async () => {
|
||||
await navigateSection('Продажи');
|
||||
await openCommand('Контрагенты');
|
||||
});
|
||||
|
||||
await step('Создать нового контрагента', async () => {
|
||||
await clickElement('Создать');
|
||||
await fillFields({ 'Наименование': 'ТД Тест', 'ИНН': '7707083893' });
|
||||
await clickElement('Записать и закрыть');
|
||||
});
|
||||
|
||||
await step('Убедиться, что элемент появился в списке', async () => {
|
||||
const t = await readTable();
|
||||
assert.tableHasRow(t, r => r['Наименование'] === 'ТД Тест');
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
Что здесь есть:
|
||||
|
||||
- **`name`** — человекочитаемое имя теста. Появится в отчёте.
|
||||
- **`tags`** — теги для фильтрации. Можно прогонять не весь набор, а только нужные: `--tags=контрагенты`.
|
||||
- **`timeout`** — сколько максимум тест может идти. По умолчанию 30 секунд, для длинных сценариев увеличиваем.
|
||||
- **Тело теста** — функция, которая получает API браузера (см. [SKILL.md](../.claude/skills/web-test/SKILL.md)) плюс `assert` и `step`.
|
||||
- **`step('имя', async () => {...})`** — обёртка шага. Имена шагов попадают в отчёт, при падении видно, какой именно шаг сломался.
|
||||
- **`assert.*`** — проверки. `assert.tableHasRow`, `assert.equal`, `assert.ok` и т.д. Если проверка не выполнилась — тест считается упавшим.
|
||||
|
||||
Имена шагов и теста — по-русски, описательные. Они показываются и в консоли, и в отчётах.
|
||||
|
||||
## Запуск и отчёты
|
||||
|
||||
### Простой прогон
|
||||
|
||||
```
|
||||
> Прогони регресс
|
||||
```
|
||||
|
||||
Модель запустит весь набор, дождётся, покажет сводку:
|
||||
|
||||
```
|
||||
✓ Открытие базы (2.1s)
|
||||
✓ Создание контрагента (8.4s)
|
||||
✗ Проведение приходной накладной (12.7s)
|
||||
└ Заполнить табличную часть (5.2s)
|
||||
Не найден столбец "Цена" в табличной части "Товары"
|
||||
скриншот: tests/учёт-поступлений/error-shot.png
|
||||
|
||||
23 пройдено, 1 упал, 0 пропущено (3 мин 42 с)
|
||||
```
|
||||
|
||||
### Подробный отчёт
|
||||
|
||||
```
|
||||
> Прогони регресс и сохрани подробный отчёт
|
||||
```
|
||||
|
||||
Модель добавит флаг записи отчёта (JSON или Allure) — потом по нему можно листать историю прогонов, видеть длительности шагов, открывать прикреплённые скриншоты.
|
||||
|
||||
Allure — стандартный визуальный отчёт с категориями падений, графиками, таймлайном. Чтобы посмотреть отчёт после прогона:
|
||||
|
||||
```bash
|
||||
# Allure CLI устанавливается отдельно (npm install -g allure-commandline)
|
||||
allure serve allure-results
|
||||
```
|
||||
|
||||
### Категории падений в Allure
|
||||
|
||||
Без дополнительной настройки Allure складывает все упавшие тесты в один общий список «Defects». Если в прогоне упало 15 тестов, не сразу понятно, что из этого — пятнадцать разных проблем или одна и та же ошибка (например, нехватка лицензии на стенде), которая зацепила пятнадцать тестов подряд.
|
||||
|
||||
Чтобы Allure группировал падения по причинам, рядом с тестами кладётся каталог `_allure/` с файлом `categories.json`. Подчёркивание в имени каталога — чтобы он не воспринимался как папка с тестами; раннер копирует его содержимое в отчёт.
|
||||
|
||||
```
|
||||
tests/моя-конфигурация/
|
||||
_allure/
|
||||
categories.json # классификация падений
|
||||
environment.properties # необязательно: URL, версия 1С, ветка git
|
||||
executor.json # необязательно: метаданные сборки CI
|
||||
_hooks.mjs
|
||||
01-вход/
|
||||
...
|
||||
```
|
||||
|
||||
`categories.json` — это список регулярных выражений, по которым ошибка теста относится к той или иной группе:
|
||||
|
||||
```json
|
||||
[
|
||||
{ "name": "Нехватка лицензий 1С",
|
||||
"matchedStatuses": ["failed", "broken"],
|
||||
"messageRegex": ".*Не обнаружено свободной лицензии.*" },
|
||||
{ "name": "Ошибка приложения 1С",
|
||||
"matchedStatuses": ["failed"],
|
||||
"messageRegex": ".*(ВызватьИсключение|В поле введены некорректные данные|Произошла ошибка).*" },
|
||||
{ "name": "Элемент не найден",
|
||||
"matchedStatuses": ["failed"],
|
||||
"messageRegex": ".*(clickElement|fillFields|selectValue).*not found.*" },
|
||||
{ "name": "Превышен лимит времени теста",
|
||||
"matchedStatuses": ["failed", "broken"],
|
||||
"messageRegex": "Timeout \\(\\d+ms\\)" },
|
||||
{ "name": "Несовпадение ожидания и факта",
|
||||
"matchedStatuses": ["failed"],
|
||||
"messageRegex": "(Expected|AssertionError).*" }
|
||||
]
|
||||
```
|
||||
|
||||
Когда вы попросите модель в первый раз настроить регресс, она положит шаблонный `categories.json` со стандартными классами. По мере того как вы будете находить новые типичные причины падений (например, специфичные для вашего расширения тексты ошибок), категории дополняются.
|
||||
|
||||
В виджете «Categories» итогового отчёта вы увидите примерно так:
|
||||
|
||||
```
|
||||
Нехватка лицензий 1С — 12 падений
|
||||
Ошибка приложения 1С — 2 падения
|
||||
Несовпадение ожидания и факта — 1 падение
|
||||
```
|
||||
|
||||
— и сразу понятно, что 12 падений — это один стенд-баг, а двумя «ошибками приложения» нужно разобраться по существу.
|
||||
|
||||
Помимо `categories.json` в каталог `_allure/` можно положить ещё два стандартных файла:
|
||||
|
||||
- **`environment.properties`** — список `ключ=значение` (URL базы, версия платформы 1С, имя ветки git, номер сборки). Покажется в отчёте в виджете «Environment». Полезно, когда регресс гоняется на нескольких стендах или после каждого билда — видно, на чём именно был получен результат. Этот файл удобно генерировать прямо в подготовке стенда (`_hooks.mjs`), а не держать статичной копией.
|
||||
- **`executor.json`** — метаданные системы сборки: ссылка на Jenkins-задачу, идентификатор запуска GitHub Actions и т.д. Нужен только если регресс запускается на сервере сборки. При локальном прогоне ничего класть не надо.
|
||||
|
||||
### Прогон части набора
|
||||
|
||||
```
|
||||
> Прогони только тесты по поступлениям товаров
|
||||
> Прогони только базовые проверки
|
||||
> Прогони только упавший вчера тест с проведением накладной
|
||||
```
|
||||
|
||||
Модель выберет нужное подмножество — по папке, по тегу или по имени теста.
|
||||
|
||||
### Принудительная пересборка стенда
|
||||
|
||||
Если хотите, чтобы перед прогоном база восстановилась с нуля:
|
||||
|
||||
```
|
||||
> Прогони регресс с полной пересборкой стенда
|
||||
```
|
||||
|
||||
Это передаст в подготовку флаг типа `--rebuild-stand` — `_hooks.mjs` пересоздаст базу из эталона. Полезно после крупных правок или если подозреваете, что предыдущие прогоны загрязнили данные.
|
||||
|
||||
## Что делать, когда тест упал
|
||||
|
||||
Модель проанализирует падение и отнесёт его к одной из трёх категорий:
|
||||
|
||||
1. **Ошибка в самом тесте.** Например, переименовали реквизит — тест ищет старое имя поля. Решение: модель обновит тест.
|
||||
2. **Ошибка в приложении.** Это и есть то, ради чего регресс существует: что-то поменялось в конфигурации, и сценарий, который раньше работал, теперь не отрабатывает. Модель опишет, что именно произошло, со скриншотом и трассировкой стека 1С, если ошибка была серверной.
|
||||
3. **Нестабильность стенда.** Apache не ответил, не освободилась лицензия, база отвалилась. Это лечится не правкой теста, а починкой подготовки стенда в `_hooks.mjs` или, реже, повторным прогоном с одним повтором.
|
||||
|
||||
Просите модель не «исправь упавший тест», а «разберись с падением» — иначе она может молча подкрутить ожидание под текущее поведение, замаскировав настоящий баг.
|
||||
|
||||
## Полезные подробности
|
||||
|
||||
### Тестовые данные
|
||||
|
||||
В прикладном решении обычно нужны какие-то стартовые данные: пара контрагентов, номенклатура, заведённые организации. Их кладём не в каждый тест, а один раз в подготовку стенда (`_hooks.mjs`) — после восстановления базы загружаются эталонные данные, на которых работают все тесты.
|
||||
|
||||
Если конкретному тесту нужны свои данные (например, документ, который мы будем редактировать), он создаёт их сам в начале и убирает в конце.
|
||||
|
||||
### Имена документов и уникальность
|
||||
|
||||
Тесты прогоняются многократно. Если тест создаёт документ «Накладная-Тест», следующий прогон может натолкнуться на старую запись. Решение — добавлять к имени метку времени:
|
||||
|
||||
```js
|
||||
const метка = 'Тест-' + Date.now();
|
||||
await fillFields({ 'Комментарий': метка });
|
||||
// ...
|
||||
const t = await readTable();
|
||||
assert.tableHasRow(t, r => r['Комментарий'] === метка);
|
||||
```
|
||||
|
||||
Модель это делает автоматически, но если правите тест руками — держите в голове.
|
||||
|
||||
### Видео при падении
|
||||
|
||||
Можно включить запись видео всех тестов — тогда при падении прикладывается не только скриншот, но и MP4 со всей сессией:
|
||||
|
||||
```
|
||||
> Прогони регресс с записью видео
|
||||
```
|
||||
|
||||
Размер прогона при этом растёт (на 2-3 минутах теста выходит 5-10 МБ), но при отладке сложного падения видео экономит кучу времени.
|
||||
|
||||
### Многоязычные конфигурации
|
||||
|
||||
Если у вас есть конфигурация с командами и реквизитами на нескольких языках, тесты пишутся под один язык (как правило, тот, в котором ведётся работа в проде). При смене языка интерфейса в браузере тесты не пройдут — модель видит другие подписи кнопок.
|
||||
|
||||
## Где смотреть дальше
|
||||
|
||||
- API браузера, которое вызывают тесты — [SKILL.md](../.claude/skills/web-test/SKILL.md).
|
||||
- Подробная инструкция для модели по написанию тестов (на английском, технический документ) — [.claude/skills/web-test/regress.md](../.claude/skills/web-test/regress.md).
|
||||
- Интерактивный режим без тестов — [web-test-guide.md](web-test-guide.md).
|
||||
- Запись видеоинструкций — [web-test-recording-guide.md](web-test-recording-guide.md).
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user