version: "1.0.1" name: test-writing description: "Use for написания тестовых модулей YaxUnit (BSL). Covers регистрация тестов, утверждения, мокирование и подготовку тестовых данных."

Написание тестов YaxUnit (BSL)

Запуск написанных тестов — отдельный навык `test-execution`.

Полная документация YaxUnit: см. `references/yaxunit-cheatsheet.md`

Расположение тестов в проекте

Тесты хранятся в отдельном расширении конфигурации: <корень проекта>/exts/TESTS/

Варианты структуры: EDT и DESIGNER

Если формат неочевиден — проверь application-*.yml / yaxunit-*.yml в корне проекта.

Не смешивай структуры: для DESIGNER обязателен Ext/, для EDT он не используется.

Новый модуль должен быть зарегистрирован в Configuration.[mdo|xml], иначе тест не подхватится раннером.

Категорические запреты:

• Тестовые исходники размещаются только в exts/TESTS/**, никогда в основной конфигурации
• exts/YAXUNIT/** никогда не изменяется вручную — это инфраструктура раннера

Именование тестовых модулей

Шаблон: <Префикс>_<ИмяОбъекта>[_<Суффикс>]

Префиксы по типу объекта

Суффиксы по типу модуля

Структура тестового модуля

Обязательно: экспортная процедура ИсполняемыеСценарии. Только регистрация тестов — никаких данных, никакой логики.

Процедура ИсполняемыеСценарии() Экспорт
 
    ЮТТесты
        .ДобавитьТестовыйНабор("Остатки")
            .ДобавитьСерверныйТест("ТестПолучитьОстатки")
            .ДобавитьСерверныйТест("ТестОстатокПустойСклад")
        .ДобавитьТестовыйНабор("Перемещение")
            .ДобавитьСерверныйТест("ТестПеремещениеМеждуСкладами");
 
КонецПроцедуры

Реализация теста

Один тест проверяет одно утверждение. Паттерн Arrange-Act-Assert:

Процедура ТестПолучитьОстатки() Экспорт
 
    // Arrange
    Склад = ЮТест.Данные().СоздатьЭлемент("Справочник.Склады");
    НоменклатураСсылка = ЮТест.Данные().СоздатьЭлемент("Справочник.Номенклатура");
 
    // Act
    Остаток = УправлениеСкладом.ПолучитьОстаток(НоменклатураСсылка, Склад);
 
    // Assert
    ЮТест.ОжидаетЧто(Остаток).Равно(0);
 
КонецПроцедуры

Утверждения (ЮТест.ОжидаетЧто)

// Базовые сравнения
ЮТест.ОжидаетЧто(Результат).Равно(42);
ЮТест.ОжидаетЧто(Результат).НеРавно(0);
ЮТест.ОжидаетЧто(Результат).Больше(10);
ЮТест.ОжидаетЧто(Флаг).ЭтоИстина();
ЮТест.ОжидаетЧто(Значение).ВСписке(МассивДопустимых);
 
// Тип и заполненность
ЮТест.ОжидаетЧто(Ссылка).ИмеетТип("СправочникСсылка.Номенклатура");
ЮТест.ОжидаетЧто(Значение).НеЯвляетсяНеопределено();
 
// Исключения
ЮТест.ОжидаетЧто(ЭтотОбъект).МетодВыбрасываетИсключение("МетодСОшибкой", Параметры);
 
// Данные ИБ
ЮТест.ОжидаетЧтоТаблицаБазы("Справочник.Склады")
    .СодержитЗаписи()
    .ГдеРеквизит("Наименование").Равно("Основной склад");

Тестовые данные (ЮТест.Данные)

// Пустышка
Склад = ЮТест.Данные().СоздатьЭлемент("Справочник.Склады");
 
// Конструктор с реквизитами
Номенклатура = ЮТест.Данные()
    .КонструкторОбъекта("Справочник.Номенклатура")
    .Установить("Наименование", "Тестовый товар")
    .Установить("ЕдиницаИзмерения", ПредопределённыйЭлемент("Классификатор.ЕдиницыИзмерения.Штука"))
    .Записать()
    .Ссылка();
 
// Документ
Документ = ЮТест.Данные().СоздатьДокумент("Документ.ПоступлениеТоваров");

Данные через ЮТест.Данные() автоматически удаляются после теста. Не создавай данные в ИсполняемыеСценарии.

Мокирование (Мокито)

Паттерн: Обучение -> Прогон -> Проверка.

Процедура ТестРасчётСкидки() Экспорт
 
    Мокито.Обучение(МодульСкидок)
        .Когда().ПолучитьПроцентСкидки(Клиент)
        .Вернуть(15);
 
    Результат = УправлениеПродажами.РассчитатьСумму(100, Клиент);
 
    ЮТест.ОжидаетЧто(Результат).Равно(85);
    Мокито.Проверить(МодульСкидок).ПолучитьПроцентСкидки(Клиент);
 
КонецПроцедуры

Сценарии мокирования

Мокито.Обучение(Модуль).Когда().МетодА(Параметр).Вернуть(42);
Мокито.Обучение(Модуль).Когда().МетодБ(Параметр).ВыброситьИсключение("Текст ошибки");
Мокито.Обучение(Модуль).Когда().МетодВ().Пропустить();
Мокито.Обучение(Модуль).Когда().МетодГ().Наблюдать();

Жизненный цикл и обработчики событий

Процедура ИсполняемыеСценарии() Экспорт
 
    ЮТТесты
        .ДобавитьТестовыйНабор("Расчёты")
            .Перед("ПередНаборомРасчёты")
            .После("ПослеКаждогоТестаОчистка")
            .ДобавитьСерверныйТест("ТестРасчётА")
            .ДобавитьСерверныйТест("ТестРасчётБ");
 
КонецПроцедуры
 
Процедура ПередНаборомРасчёты() Экспорт
    ЮТест.Контекст().УстановитьЗначение("Ставка", 18);
КонецПроцедуры

Контекст — передача данных между методами

ЮТест.Контекст().УстановитьЗначение("МоёЗначение", Данные);
Данные = ЮТест.Контекст().Значение("МоёЗначение");

Параметризованные тесты

Процедура ИсполняемыеСценарии() Экспорт
 
    Варианты = ЮТест.Варианты()
        .Добавить(0,   "Нулевое количество",  0)
        .Добавить(10,  "Положительное",       100)
        .Добавить(-5,  "Отрицательное",       0);
 
    ЮТТесты
        .ДобавитьТестовыйНабор("Расчёт суммы")
            .ДобавитьСерверныйТест("ТестРасчётСуммы")
                .СПараметрами(Варианты);
 
КонецПроцедуры
 
Процедура ТестРасчётСуммы(Количество, Описание, ОжидаемаяСумма) Экспорт
    Результат = МойМодуль.РассчитатьСумму(Количество);
    ЮТест.ОжидаетЧто(Результат)
        .НазваниеПроверки(Описание)
        .Равно(ОжидаемаяСумма);
КонецПроцедуры

Изоляция тестовых данных (MUST)

Тест, пишущий в БД, обязан откатывать свои изменения. Без изоляции каждый прогон оставляет мусор в базе, тесты теряют идемпотентность.

Транзакционная изоляция через .ВТранзакции()

Fluent-метод .ВТранзакции() вызывается сразу после ДобавитьТестовыйНабор() — настройка применяется на уровне набора (рантайм ищет по иерархии: Тест → Набор → Модуль). Перед каждым тестом набора YaxUnit открывает транзакцию, после теста — откатывает её.

Процедура ИсполняемыеСценарии() Экспорт
 
    ЮТТесты
        .ДобавитьТестовыйНабор("Проведение документа")
            .ВТранзакции()                              // ← изоляция: откат после каждого теста
            .ДобавитьСерверныйТест("ТестПроведениеСДоговором")
            .ДобавитьСерверныйТест("ТестПроведениеСКорректнойСуммой");
 
КонецПроцедуры

Справочники — только через ЮТест.Данные()

Элементы справочников создавать через ЮТест.Данные().СоздатьЭлемент(...) или КонструкторОбъекта(...).Записать(). Такие объекты трекаются YaxUnit и удаляются автоматически. Прямой вызов Справочники.X.СоздатьЭлемент() — антипаттерн: объект не трекается, остаётся в базе.

Документы через СоздатьДокумент() — обязательный teardown

ЮТест.Данные().СоздатьДокумент(...) трекается и удаляется автоматически. Но если документ создаётся через Документы.X.СоздатьДокумент() напрямую — он НЕ трекается, нужен явный teardown в .После("ИмяПроцедурыОчистки").

Исключения из .ВТранзакции()

Три ситуации, когда .ВТранзакции() применять НЕЛЬЗЯ — при каждой обязателен комментарий-обоснование у набора и teardown через .После():

// Исключение (а): негативный тест — ожидаемый Отказ отравляет внешнюю транзакцию.
// Изоляция: ЮТест.Данные() + .УдалениеТестовыхДанных() + teardown в .После().
ЮТТесты
    .ДобавитьТестовыйНабор("Запрет проведения")
        .УдалениеТестовыхДанных()
        .После("ОчиститьДокументыЗапретПроведения")
        .ДобавитьСерверныйТест("ТестЗапретБезДоговора");

Паттерн перечитывания объекта при перепроведении

Тест, меняющий режим записи документа, обязан перечитывать объект между сменами — это моделирует поведение формы:

// Провести
ДокОбъект = ДокСсылка.ПолучитьОбъект();
ДокОбъект.Записать(РежимЗаписиДокумента.Проведение);
 
// Отменить проведение — перечитываем, как форма
ДокОбъект = ДокСсылка.ПолучитьОбъект();
ДокОбъект.Записать(РежимЗаписиДокумента.ОтменаПроведения);

Ограничение платформы 8.3.27: программное перепроведение в серверной сессии иногда даёт [ОшибкаХранимыхДанных] — стек без прикладных кадров, ни перечитывание, ни .ВТранзакции() не помогают. Идемпотентность перепроведения в таком случае проверяется сценарным слоем (Vanessa), юнит-тест оформляется через ЮТест.Пропустить() с явным обоснованием.

Чеклист самоочистки — проверка запросами (MUST после написания/правки пишущих тестов)

Изоляция декларируется в коде (.ВТранзакции(), teardown), а доказывается фактом — счётчиками в БД до/после прогона. Зелёный прогон НЕ доказывает чистоту: тест может пройти и оставить мусор.

1. Карта таблиц. Составь список таблиц, в которые тесты модуля могут писать: всё, что создают Перед-хендлеры и тела тестов (справочники, документы, регистры), включая объекты контекстных хелперов (СоздатьКонтекстТеста и т.п.).
2. Счётчики ДО. Для каждой таблицы — ВЫБРАТЬ КОЛИЧЕСТВО(*) ИЗ Справочник.X (платформенный запрос: MCP execute_query / консоль запросов). Для регистров сведений — счётчик по измерению-маркеру теста, не по всей таблице.
3. Прогон + счётчики ПОСЛЕ. Прогнать модуль целиком, снять те же счётчики. Дельта по каждой таблице = 0.
4. Второй прогон. Повторить: GREEN + дельта снова 0. Первый прогон мог «съесть» чужой накопленный мусор и замаскировать собственный — повторяемость обязательна.
5. Дельта ≠ 0 → виновник. Найти оставшиеся объекты по именам/маркерам (ВЫБРАТЬ Наименование ... ГДЕ Наименование ПОДОБНО "...%"), определить создающий хендлер/тест, добавить teardown, повторить чеклист с шага 2.

Ловушки (прецедент TASK-173 / TASK-165.7):

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

Слои и фазы TDD, границы ролей

Тесты и реализация пишутся разными агентами в разных фазах. Автор тестов не знает реализацию, автор кода не модифицирует тесты.

Phase 3a: Scenario-Author  → .feature (BDD)   ┐ параллельно
Phase 3b: Developer-Tests  → unit-тесты (Red)  ┘
Phase 3c: Developer-Code   → код (Green)
Phase 4:  Tester           → edge cases, регрессия, BDD + unit

Слои тестирования

Phase 3a и 3b — параллельно. Phase 3c стартует после завершения обоих.

Границы агентов

• Scenario-Author: НЕ пишет unit-тесты, НЕ запускает сценарии, НЕ расширяет за пределы спецификации
• Developer-Tests: MUST-сценарии + базовые негативы; НЕ покрывает комбинаторные edge cases и интеграцию
• Tester: дополняет покрытие; НЕ дублирует тесты Developer; НЕ правит BSL-код

Правило при падении теста у Tester

Тест упал
  ├── Ошибка в тесте → Tester исправляет (test_error)
  └── Баг в коде → СТОП. Метка implementation_error + описание.
                   Оркестратор возвращает задачу Developer.

User/Role context в Test Plan: если код использует SetPrivilegedMode, проверки ролей (AccessRight, RoleAvailable) или результат зависит от текущего пользователя — спецификация ДОЛЖНА в разделе «Test Plan» явно указать для каждого теста: имя пользователя/набор ролей, требуемый режим (привилегированный или нет), ожидаемый результат (успех/отказ). Без этого тест под full-rights runner-ом (например AgentAI) даст false-positive: пройдёт «по совпадению» через привилегированную ветку, не проверив роле-зависимое поведение. Если для unit это технически невозможно — фиксируется в спеке отдельным ADR с переносом в integration scope (Phase 4).

depends_on: []