1c Vanessa Steps

---
name: 1c-vanessa-steps
description: "Реестр шагов Vanessa Automation (BDD для 1С:Предприятие) - 1569 шагов с описаниями, поиск шага по смыслу и валидация готового сценария .feature. Используй ВСЕГДА, когда пишешь, правишь или проверяешь сценарии Vanessa на Gherkin: модель уверенно сочиняет шаги, которых в Vanessa нет, и такой сценарий падает только на прогоне. Триггеры: написать сценарий Vanessa, BDD-тест для 1С, feature-файл, Gherkin для 1С, какой шаг открывает форму, есть ли такой шаг, проверь сценарий, валидация feature, Turbo Gherkin, шаги Ванессы."
argument-hint: "search <запрос> | validate <файл.feature> | stats"
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
---

# Шаги Vanessa Automation: поиск и валидация

Библиотека из **1569 шагов** Vanessa Automation с описаниями и типами, плюс два инструмента:
поиск подходящего шага и проверка готового сценария.

> **Зачем.** Шаг Gherkin - это не свободный текст, а вызов конкретной реализации из Vanessa.
> Модель, не имея реестра, пишет правдоподобную фразу ("И я телепортирую документ в прошлое"),
> сценарий выглядит корректно и падает только на прогоне в базе - дорого и не сразу понятно.
> Реестр закрывает это на этапе написания.

## When to Use

- Пишешь новый сценарий Vanessa - **сначала найди шаги**, потом составляй из найденного.
- Правишь чужой сценарий и не уверен, существует ли шаг.
- Получил сценарий от заказчика или из другого проекта - проверь перед запуском.
- Нужно понять, каким шагом делается конкретное действие (открыть форму, заполнить поле,
  проверить значение, подключить TestClient, работать с файлами).

## When NOT to Use

- Юнит-тесты на YaXUnit - это не Gherkin, реестр к ним не относится (см. `testing-patterns.md`).
- Отладка падающего прогона, где шаг ЕСТЬ, но ведет себя не так - это про данные и конфигурацию,
  а не про реестр шагов.

## Порядок работы

### 1. Найти шаг вместо того, чтобы его сочинить

```bash
python skills/1c-vanessa-steps/scripts/search_steps.py --query "открыть форму документа" --top 5 --format human
python skills/1c-vanessa-steps/scripts/search_steps.py --category UI --subcategory Формы --format human
python skills/1c-vanessa-steps/scripts/search_steps.py --stats
```

Запрос - на русском, словами задачи. Вывод `--format json` удобен для дальнейшей обработки,
`human` - для чтения.

**Критерий:** каждый шаг будущего сценария найден в реестре. Не нашел - это сигнал, что действие
делается иначе (другим шагом или последовательностью), а НЕ разрешение придумать формулировку.

### 2. Собрать сценарий

Структура файла, обязательные строки заголовка, типовые связки - `references/scenario-templates.md`.
Правила формулировок и работа с параметрами шагов - `references/writing-scenarios.md`.

### 3. Проверить перед сдачей

```bash
python skills/1c-vanessa-steps/scripts/validate.py "путь/к/сценарию.feature"
```

Отчет дает: сколько шагов валидно, какие строки не найдены в реестре, и рекомендации. Ошибки
структуры (нет строки языка или кодировки) он тоже ловит.

**Критерий завершения:** невалидных шагов ноль. Один невалидный шаг - сценарий не готов, даже если
остальные девяносто девять на месте.

### 4. Разбор спорного случая

Когда шаг похож на существующий, но не совпадает дословно, помогает разбор по смыслу:
`references/semantic-validation.md` - как сопоставляются параметры и почему близкий по виду шаг
может быть другим шагом.

## Состав

| Путь | Что |
|------|-----|
| `data/steps-library.json` | реестр: 1569 шагов, 13 категорий, 374 подкатегории |
| `scripts/search_steps.py` | поиск по запросу, категории, подкатегории; статистика |
| `scripts/validate.py` | проверка `.feature`: существование шагов и структура файла |
| `scripts/indexer.py` | построение индексов для ускорения поиска на больших прогонах |
| `references/steps-compact.md` | весь реестр компактным списком - когда нужен просмотр глазами |
| `references/writing-scenarios.md` | как писать сценарии: формулировки, параметры, типовые ошибки |
| `references/scenario-templates.md` | готовые шаблоны сценариев |
| `references/semantic-validation.md` | сопоставление шагов по смыслу, разбор параметров |

Зависимостей нет - только стандартная библиотека Python 3.8+.

## Ограничения

- Реестр - **снимок** библиотеки шагов на момент сборки. Своя сборка Vanessa, плагины или шаги из
  подключенных библиотек проекта в нем отсутствуют: шаг, не найденный валидатором, может быть
  проектным. Проверять по своей поставке, а не считать вывод валидатора приговором.
- Валидатор проверяет СУЩЕСТВОВАНИЕ шага и структуру файла, а не осмысленность сценария. Логику
  проверки, порядок шагов и тестовые данные он не оценивает.

## Источник

Реестр шагов и инструменты поиска и валидации взяты из проекта
[va-ai](https://github.com/Nikolay-Shirokov/va-ai) (MIT, (c) Nikolay Shirokov) и адаптированы под
раскладку этого набора. Сам Vanessa Automation - отдельный проект, см.
[vanessa-automation](https://github.com/Pr-mex/vanessa-automation).