vanessa-authoring

name	vanessa-authoring
description	Vanessa: написание и уточнение feature-сценариев
uses_capabilities	["run_vanessa","build_project"]

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

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

1. Определи источник требования — спецификация или бизнес-кейс (vanessa-scenario-policy).
2. Определи под каким пользователем выполняется сценарий (см. «Пользовательский контекст»).
3. Найди подходящие шаги: сначала в библиотеке Vanessa, затем в сценариях проекта.
4. Исследуй интерфейс и заполни форму вручную. Предпочтительный путь — MCP-инструменты Vanessa Automation через v8-session-manager (см. «MCP-исследование через Vanessa Automation»). Для UI/UX-контроля формы применяй va-visual-check: VA MCP screenshot route, Linux/Xvfb рецепт и browser fallback с фиксацией причины. В любом варианте зафиксируй точные имена и заголовки элементов, поля, кнопки, закладки до ссылок на них в шагах; не угадывай идентификаторы (заголовок Title vs имя name — см. vanessa-scenario-policy).
5. Напиши один smoke-сценарий: открыть → одно действие → одно наблюдаемое следствие.
6. Если шага нет — пометь # unknown_step_candidate, не изобретай BSL-шаг.
7. Передай сценарий на прогон через v8-runner (v8-runner test va).

---

MCP-исследование через Vanessa Automation

Этот раздел фиксирует универсальный workflow, проверенный на Vanessa Automation 1.2.043.28. Для другой версии сначала сверяй поведение с официальной инструкцией VA и live-схемами инструментов.

Официальный источник Vanessa Automation: https://github.com/Pr-Mex/vanessa-automation. Инструкции для AI/MCP находятся в docs/AI/. Обновления VA бери из официального репозитория/релизов, а не правками vendor-кода в проекте. Для WS-запуска используются наш форк v8-runner https://github.com/SteelMorgan/v8-runner-rust и v8-session-manager https://github.com/1c-neurofish/v8-session-manager.

Проверка версии и готовности

1. Если VA manager-сессия ещё не поднята, запусти её строго по навыку v8-runner (раздел «Vanessa Automation MCP через session-manager»); не собирай строку запуска в этом навыке.
2. Через session_list дождись live-сессии kind=vanessa_test_client, где появились VA-tools: например get_VanessaAutomation_state, connect_test_client, get_form_analysis, manage_command_interface.
3. Вызови get_environment_data или ближайший доступный VA-инструмент окружения и зафиксируй версию Vanessa Automation в контексте задачи.
4. Если нужны служебные data-tools (get_table_data, get_object_attributes), проверь, что служебное расширение VA загружено в тестируемую ИБ. Наличие свежих файлов расширения в source недостаточно: runtime-инструменты ищут формы в подключенной базе.

Обязательная последовательность работы

1. Подключить тест-клиент. Перед любыми инструментами, которые читают/управляют интерфейсом тестируемого приложения, вызови connect_test_client с профилем тест-клиента. Профиль выбирай из настроек VA/таблицы профилей ДанныеКлиентовТестирования в VAParams, не угадывай имя. Как формировать tools.va / tests.va в v8project.yaml и профиль TestClient внутри VAParams — см. v8-runner, references/config-and-backends.md.
2. Исследовать форму через VA-tools. Используй live-схемы tools и их описания из session_list / tools/list, потому что набор инструментов расширяется между версиями VA. Не фиксируй закрытый список как полный. На момент VA 1.2.043.28 основные классы инструментов: командный интерфейс, список окон, данные активного окна, анализ формы, действия с элементами формы, чтение реквизитов объекта, чтение таблиц/данных, скриншоты, запись действий пользователя, выполнение шагов .feature.
3. Снять визуальный контрольный скриншот. Для любой UI/UX-проверки после открытия нужной формы применяй va-visual-check: сначала VA MCP PNG, затем при необходимости Linux/Xvfb рецепт или browser fallback с фиксацией причины.
4. Не записывать данные без цели теста. Для исследования заполнения формы можно открыть форму создания, читать реквизиты и пробовать навигацию; запись/проведение выполняй только если это нужно для проверки заполнения или сценария, и соблюдай правила изоляции тестовых данных.
5. Закрыть тест-клиент. После исследования, прогона или ошибки обязательно вызови close_test_client для подключенного профиля. Если VA manager-сессия запускалась вручную для исследования, после завершения работы останови и её.

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

• вызывать get_form_analysis, manage_command_interface, manage_form_elements, get_object_attributes, screenshot/recording-инструменты до connect_test_client;
• считать внутренний список окон get_window_list_testclient визуальным скриншотом: он нужен для структуры и навигации, а UI/UX-приёмка требует PNG по правилам va-visual-check;
• считать наличие имени tool в кешированном tools/list доказательством доступности — проверяй live-сессию нужного kind;
• держать тест-клиент открытым после завершения операции;
• править vendor-код VA/VAExtension, когда проблема в версии, загрузке расширения или настройке запуска.

Встраивание в сценарный авторинг

Перед написанием .feature по новой форме сначала проведи MCP-исследование:

1. Открой раздел/команду через manage_command_interface или прямую навигацию.
2. Получи get_active_window_data и get_form_analysis.
3. Сделай визуальный PNG формы по va-visual-check и проверь его по form-visual-requirements.
4. Для формы объекта получи get_object_attributes в режимах реквизитов шапки и табличных частей.
5. При необходимости получи справочные данные через get_table_data, чтобы выбирать существующие валидные значения.
6. По результатам зафиксируй точные команды, имена элементов, обязательные поля, условную видимость/доступность, визуальные замечания и порядок заполнения в контексте сценария.
7. Только после этого пиши Gherkin-шаги и подсценарии.

Ручное заполнение формы перед сценарием (MUST)

Перед написанием НОВОГО сценария по документу агент сначала заполняет форму через Vanessa/TestClient, сверяясь с реальным составом формы на каждом шаге. Платформенный TestClient MCP допустим только для действия, которого VA MCP принципиально не предоставляет, с записью причины в контекст. .feature пишется только ПОСЛЕ успешного заполнения через VA/TestClient. Web-клиент допустим только для браузерных функций, которых VA MCP принципиально не поддерживает.

Требование	Описание
Снимок после каждого поля	После изменения каждого поля заново снимать состав формы (get_form_analysis, get_active_window_data, чтение элемента/таблицы): значение поля меняет видимость, доступность и обязательность других полей (обработчики ПриИзменении). Визуальный PNG делай по va-visual-check на ключевых состояниях формы и обязательно для итоговой UI/UX-приёмки. Полный набор обязательных полей выясняется итеративно, не угадывается заранее
Изучить Подсказку и справочные данные	До заполнения прочитать Help/подсказку документа и справочные данные — понять сценарии работы и порядок заполнения. Могут быть пусты, но у типовых объектов часто заполнены
Все ключевые поля шапки	Заполнять по смысловой оценке назначения документа (Организация, Контрагент, Соглашение, Склад и т.п. — то, что требует смысл документа)
Обязательные табличные части	Заполнять обязательные ТЧ (обычно товары / по смыслу документа) хотя бы несколькими строками; проверять, что все поля строк заполнены
Полосы прокрутки	При визуальном анализе помнить: форма и ТЧ могут иметь полосы прокрутки, скрывающие часть полей — прокручивать, чтобы увидеть все элементы, а не только видимую область
Переиспользуемые «кубики»	Сценарии заполнения оформлять как переиспользуемые подсценарии (@exportscenarios), чтобы другие тесты с тем же документом собирались из них как из кубиков конструктора. Один документ → может иметь несколько сценариев заполнения
Запись и проведение	При ручном прогоне документ записать и провести (если этого требует смысл теста) — убедиться, что заполнение реально проходит, а не только выглядит полным
Анализ ошибок заполнения	Запись/проведение могут дать ошибки — всплывающие сообщения в нижней части экрана (могут иметь собственную полосу прокрутки — прокручивать и читать все). Каждую разобрать, скорректировать заполнение и повторить, пока документ не запишется/проведётся чисто
Порядок	Сначала успешное ручное заполнение со сверкой состава, запись и проведение документа и устранение всплывающих ошибок → затем запись .feature

---

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

# language: ru
# encoding: utf-8
# Задача: task-103 — Оформление заказа клиента через портфель

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

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

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

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

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

---

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

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

Как определить пользователя:

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

Один пользователь (в секции Контекст:):

Дано Я запускаю тест-клиент для пользователя "SalesManager" с паролем "123" или подключаю уже существующий

Несколько пользователей (в теле сценария — именованные TestClient):

И я подключаю TestClient "Менеджер" логин "SalesManager" пароль "123"
И я подключаю TestClient "Руководитель" логин "Director" пароль "456"

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

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

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

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

---

Двухсессийный сплит (MUST)

.feature-файл логически делится на две части:

1. Setup / инфраструктура — выполняется под техническим пользователем (AgentAI в этом проекте): подготовка тестовых данных (создание документов, элементов справочников, записей регистров), шаги VAExtension (Расширение), BSL-фикстуры из vanessa-tests/support/, всё что требует технических ролей вне нормального доступа бизнес-пользователя.
2. Бизнес-флоу (верификация) — выполняется под конкретным бизнес-пользователем (например Gavrilova Natalia для OC-23400): только шаги, проверяющие пользовательское поведение под тестом. Бизнес-пользователь НЕ должен получать технические роли (например роли из VAExtension.cfe) лишь ради прохождения шага.

Переключение сессий:

И я закрываю сеанс TESTCLIENT

или

И я закрываю TestClient "<имя>"

после чего открывается новая сессия:

Дано я подключаю TestClient "<роль>" логин "<пользователь>" пароль "<пароль>"

Обоснование (Infostart id=249957, id=249958): если бизнес-флоу выполняется с полными правами, тест перестаёт проверять реальные ролевые ограничения и даёт ложное ощущение правильности. Выдача бизнес-пользователю технических ролей ради удовлетворения инфраструктурного шага — это тот же антипаттерн в другой форме.

Антипаттерн: помещать шаги (Расширение) / фикстуры в сессию бизнес-пользователя, а потом «починить» падение выдачей ему технических ролей. Вместо этого — переместить шаг в блок setup под техническим пользователем.

---

Поиск шагов

Библиотека: /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, Прочее, Файлы, Переменные и т.д.)

---

Теги

Тег	Смысл
@task-<ID>	Привязка к задаче трекера (MUST, vanessa-scenario-policy)
@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/SKILL.md
• framework/rules/vanessa-test-isolation-policy/SKILL.md
• framework/rules/vanessa-tests-location/SKILL.md
• framework/rules/vanessa-run-loop/SKILL.md
• framework/skills/tool-usage/vanessa/vanessa-diagnostics/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/SKILL.md requires:
• tools

---