vanessa-authoring

---
name: vanessa-authoring
description: Создание и доработка feature-сценариев Vanessa Automation по реальным требованиям проекта. Используй, когда нужно написать или обновить сценарный тест, а не просто запустить его.
---

# Авторинг сценариев Vanessa Automation

## Алгоритм написания

1. Определи источник требования — спецификация или бизнес-кейс (`vanessa-scenario-policy`).
2. Определи **под каким пользователем** выполняется сценарий (см. «Пользовательский контекст»).
3. Найди подходящие шаги: сначала в библиотеке Vanessa, затем в сценариях проекта.
4. Напиши один smoke-сценарий: открыть → одно действие → одно наблюдаемое следствие.
5. Если шага нет — пометь `# unknown_step_candidate`, не изобретай BSL-шаг.
6. Передай сценарий в `vanessa-run` для прогона.

---

## Анатомия feature-файла

```gherkin
# language: ru
# encoding: utf-8

@тег-фичи
Функциональность: Краткое название

Как <роль пользователя>
Я хочу <что сделать>
Чтобы <бизнес-польза>

Контекст:
    Дано Я запускаю тест-клиент для пользователя "Логин" с паролем "Пароль" или подключаю уже существующий

Сценарий: Название сценария
    Когда <действие>
    И    <следующее действие>
    Тогда <ожидаемый результат>
```

- `Контекст:` выполняется **перед каждым** сценарием файла.
- Ключевые слова шагов: `Дано`, `Когда`, `Тогда`, `И`, `Затем` — взаимозаменяемы синтаксически.
- Строки — в апострофах или кавычках; спецсимволы: `\'`, `\"`, `\\`.
- `Структура сценария:` + `Примеры:` — запускает сценарий по каждой строке таблицы параметров.
- `@tree` в заголовке — включает Turbo Gherkin: отступы Tab задают дерево шагов (пробелы недопустимы!).
- `@exportscenarios` — делает сценарий доступным как подсценарий из другого feature-файла.

---

## Пользовательский контекст

**MUST:** каждый сценарий выполняется под конкретным бизнес-пользователем, а не под admin/AgentAI.
Исключение — только если проверяемая функция доступна исключительно администратору.

**Как определить пользователя:**
1. Указан в описании задачи → использовать его.
2. Не указан → **спросить у человека** до написания сценария.

**Один пользователь** (в секции `Контекст:`):
```gherkin
Дано Я запускаю тест-клиент для пользователя "SalesManager" с паролем "123" или подключаю уже существующий
```

**Несколько пользователей** (в теле сценария — именованные TestClient):
```gherkin
И я подключаю TestClient "Менеджер" логин "SalesManager" пароль "123"
И я подключаю TestClient "Руководитель" логин "Director" пароль "456"

И я активизирую TestClient "Менеджер"
# ... шаги от имени менеджера ...

И я активизирую TestClient "Руководитель"
# ... шаги от имени руководителя ...

И я закрываю TestClient "Менеджер"
И я закрываю TestClient "Руководитель"
```

> Пароль — plain text в feature-файле. Тестовые пользователи должны иметь простой или пустой пароль (`пароль ""`).

---

## Поиск шагов

Библиотека: `/opt/onescript/2.0.0/lib/add/features/libraries/`

| Категория | Файл библиотеки |
|-----------|-----------------|
| Интерфейс, поля, кнопки, закладки | `UITestRunner/РаботаСИнтерфейсом.feature` |
| Таблицы (ТЧ) | `UITestRunner/РаботаСТаблицами.feature` |
| Состояние элементов формы | `UITestRunner/СостояниеЭлементаФормы.feature` |
| Флаги / переключатели | `UITestRunner/РаботаСФлагами.feature` |
| Сообщения пользователю | `UITestRunner/РаботаСОкномСообщений.feature` |
| Данные в БД, справочники | `Данные/ЗапросыКБД.feature` |
| Один / несколько TestClient | `UITestRunner/ОткрытьTestClient.feature`, `UITestRunner/ПодключениеНесколькихКлиентовТестирования.feature` |
| Условия, переменные | `Условие/Условие.feature` |
| Пауза | `Пауза/СделатьПаузу.feature` |

Шпаргалка частых шагов с синтаксисом → `references/steps-cheatsheet.md`.

**Полная библиотека:** `references/steps.json` (1116 шагов). **Не читай целиком** — используй `grep` для поиска по ключевым словам из задачи. Структура каждой записи:
- `ИмяШага` — пример вызова с параметрами
- `ОписаниеШага` — что делает шаг
- `ПолныйТипШага` — категория (UI, Прочее, Файлы, Переменные и т.д.)

---

## Теги

| Тег | Смысл |
|-----|-------|
| `@draft` / `@Draft@` | Исключить из прогона при запуске каталога |
| `@manual-data` | Сценарий зависит от данных, созданных вручную |
| `@regression` | Регрессионный тест |
| `@ui` | UI-тест через TestClient |
| `@tree` | Turbo Gherkin: отступы Tab = вложенность (пробелы запрещены) |
| `@exportscenarios` | Сценарий вызывается как подсценарий из другого файла |
| `@IgnoreOnXxx` | Системный: пропустить в указанном окружении |

---

## Антипаттерны

| Антипаттерн | Последствие |
|-------------|-------------|
| Сценарий под admin без обоснования | Не проверяет реальные права пользователя |
| Шаг проверяет внутреннюю деталь (вызов метода, прямой запрос в БД) | Хрупкий: нет наблюдаемого UI-поведения |
| Изобретённый шаг вместо поиска в библиотеке | Не резолвится при запуске |
| Длинный сценарий (7+ действий) | Сложно локализовать падение |
| Подготовка данных смешана с проверкой | Нарушает Given/Then разделение |

---
depends_on:
  - framework/rules/vanessa-scenario-policy.mdc
  - framework/rules/vanessa-test-isolation-policy.mdc
  - framework/rules/vanessa-tests-location.mdc
  - framework/rules/vanessa-run-loop.mdc
  - framework/skills/tool-usage/vanessa/vanessa-run/SKILL.md
  - framework/skills/tool-usage/vanessa/vanessa-diagnostics/SKILL.md
  - framework/skills/tool-usage/forms/form-element-mapping/SKILL.md
requires:
  - tools
---