draft

documentation/docs/recommendations/avaliable-code.md

@@ -0,0 +1,14 @@
+# Ограничения тестируемого кода
+
+## Только синхронных код
+
+YAxUnit выполняет тесты последовательно, вызов каждого теста это синхронный вызов тестового метода, в связи с этим не поддерживается:
+
+* Тестирование методов построенных на обработчиках
+* Тестирование асинхронных методы
+
+## Тестирование форм
+
+YAxUnit плохо подходит для тестирования форм. Формы, это в первую очередь про взаимодействие с пользователем, с другими объектами системы. 
+Для их проверки лучше подходят такие инструменты как [vanessa-automation]([vanessa-automation](https://github.com/Pr-Mex/vanessa-automation)), [add](https://github.com/vanessa-opensource/add) или [tester](https://github.com/grumagargler/tester). Они позволяют проще и комплексно проверить работу форм.  
+Если же в форме расположена сложная логика слабо связанная с отображением, то ее можно вынести в общий модуль, который будет вызываться из формы и тестировать уже методы этого общего модуля.

documentation/docs/cook-book/recommendations/common-recommendations.md → documentation/docs/recommendations/common-recommendations.md

@@ -26,8 +26,9 @@ sidebar_position: 1
 * Сценарий, в котором он тестируется.
 * Ожидаемое поведение при вызове сценария.
 
-Почему это важно?
+:::note Почему это важно?
 Стандарты именования важны, поскольку они явно выражают цель теста. Тесты — это не просто проверка работоспособности вашего кода, но и документация. Посмотрев на набор юнит-тестов, вы должны иметь возможность понять поведение вашего кода, не заглядывая в сам код. Кроме того, когда тесты не проходят, вы точно видите, какие сценарии не соответствуют вашим ожиданиям.
+:::
 
 ```bsl title="Плохо"
 Процедура Тест_ОднаСтрока() Экспорт
@@ -40,7 +41,7 @@ sidebar_position: 1
 КонецПроцедуры
 ```
 
-```bsl title="Хорошо"
+```bsl title="Лучше"
 Процедура ДобавитьСтроку_БезДополнения_ВернетТужеСтроку() Экспорт
 
     Результат = ЮТСтроки.ДобавитьСтроку("Иванов", "");
@@ -59,10 +60,11 @@ sidebar_position: 1
 * Выполните **действие** над объектом.
 * **Проверьте**, что всё соответствует ожиданиям.
 
-### Почему это важно?
+:::note Почему это важно?
 
 * Такой подход четко разделяет тестируемую логику и этапы подготовки и проверки.
 * Снижает вероятность смешивания утверждений с кодом действия.
+:::
 
 Читаемость — один из важнейших аспектов при написании тестов. Разделение этих действий в тесте ясно подчеркивает зависимости, необходимые для вызова вашего кода, как именно ваш код вызывается и что вы пытаетесь проверить. Хотя возможно объединить некоторые шаги и уменьшить размер теста, основной целью является максимальная читаемость теста.
 
@@ -80,7 +82,7 @@ sidebar_position: 1
 КонецПроцедуры
 ```
 
-```bsl title="Хорошо"
+```bsl title="Лучше"
 Процедура ДобавитьСтроку_БезДополнения_ВернетТужеСтроку() Экспорт
 
     // Подготовка
@@ -101,10 +103,11 @@ sidebar_position: 1
 
 Входные данные для юнит-теста должны быть как можно проще, чтобы проверить поведение, которое вы сейчас тестируете.
 
-### Почему это важно?
+:::note Почему это важно?
 
 * Тесты становятся более устойчивыми к будущим изменениям в кодовой базе.
 * Они ближе к тестированию поведения, а не реализации.
+:::
 
 Тесты, которые включают больше информации, чем требуется для прохождения, могут содержать больше ошибок и затруднять понимание намерения. При написании тестов важно сосредоточиться на поведении. Установка дополнительных свойств в моделях или использование ненулевых значений, когда это не требуется, отвлекает от того, что вы пытаетесь доказать.
 
@@ -126,7 +129,7 @@ sidebar_position: 1
 КонецПроцедуры
 ```
 
-```bsl title="Хорошо"
+```bsl title="Лучше"
 Процедура ДобавитьСтроку_БезДополнения_ВернетТужеСтроку() Экспорт
 
     // Подготовка
@@ -146,10 +149,11 @@ sidebar_position: 1
 
 Именование переменных в юнит-тестах так же важно, если не более важно, чем в рабочем коде. Юнит-тесты не должны содержать магических строк.
 
-### Почему это важно?
+:::note Почему это важно?
 
 * Устраняет необходимость читателю теста проверять основной код, чтобы понять, что делает значение особенным.
 * Явно показывает, что вы пытаетесь *проверить*, а не *выполнить*.
+:::
 
 "Магические" строки могут вызывать путаницу у читателя ваших тестов. Если строка выглядит необычно, может возникнуть вопрос, почему для параметра или возвращаемого значения выбрано определенное значение. Такие строки могут отвлекать внимание от теста и заставлять заглядывать в детали реализации.
 
@@ -168,7 +172,7 @@ sidebar_position: 1
 КонецПроцедуры
 ```
 
-```bsl title="Хорошо"
+```bsl title="Лучше"
 Процедура ДобавитьСтроку_БезДополнения_ВернетТужеСтроку() Экспорт
 
     ИсходнаяСтрока = ЮТест.Данные().СлучайнаяСтрока();
@@ -228,7 +232,7 @@ sidebar_position: 1
 КонецПроцедуры
 ```
 
-```bsl title="Хорошо"
+```bsl title="Лучше"
 Процедура ДобавитьСтроку_БезДополнения_ВернетТужеСтроку() Экспорт
 
     ИсходнаяСтрока = ЮТест.Данные().СлучайнаяСтрока();
@@ -408,7 +412,7 @@ sidebar_position: 1
 КонецПроцедуры
 ```
 
-```bsl title="Хорошо"
+```bsl title="Лучше"
 Процедура ДобавитьСтроку_БезДополнения_ВернетТужеСтроку() Экспорт
 
     ИсходнаяСтрока = ЮТест.Данные().СлучайнаяСтрока();

documentation/docs/recommendations/index.md

@@ -0,0 +1,26 @@
+# Рекомендации
+
+Модульные тесты - это инструмент разработчика улучшающий качества работы.
+
+* Модульные тесты это код.
+* Тесты идут совместно с доработками (при использовании git)
+* Быстрый ответ
+* Высокая скорость реализации и, соответственно, низкая стоимость. На проверку небольшой функции уходит всего несколько секунд. Изолированность юнитов позволяет проверять работоспособность нескольких модулей одновременно.
+* Простота автоматизации. Unit тест исследует ответ кода на ввод данных и определенные действия. Он не требует проиграть сценарий взаимодействия конечного пользователя с новой функцией, поэтому автоматизация процесса не отнимает много сил и времени.
+
+На больших и сложных проектах стопроцентного покрытия кода тестами достичь сложно. К тому же, это нерационально. Показатель 70–90% считается хорошим. Он позволяет выявить максимальное количество ошибок. Мы собрали несколько практических советов по увеличению процента покрытия кода:
+
+* Пишите unit тест на каждый новый код сразу же.
+* Используйте готовые решения – тестовые фреймворки.
+* Создавайте тесты для проверки только одной функции.
+* Используйте негативные тесты для проверки поведения программы в случае ввода неправильных данных.
+* Используйте мутационные фреймворки с функцией изменения констант и условий для проверки качества unit тестов.
+* Проверяйте тесты на стабильность.
+* Следите за скоростью выполнения теста.
+
+
+## Рекомендации по модульному тестированию с использованием YAxUnit
+
+Кроме [общих рекомендаций](common-recommendations.md)
+
+* Структура тестовых модулей: Модуль тестового набора должен соответствовать объекту решения, который он будет тестировать. Для этого мы предлагаем [схему наименования модулей](../getting-started/structure.md#схема-наименования-модулей)

documentation/docs/recommendations/links.md

@@ -0,0 +1,5 @@
+# Полезные ссылки
+
+* [Код без тестов — легаси](https://habr.com/ru/companies/dododev/articles/544110/)  
+  О легаси, о его изменении и покрытии тестами.
+* https://less.works/ru/less/technical-excellence/unit-testing

documentation/docs/recommendations/what-to-test.md

@@ -0,0 +1,25 @@
+# Что тестировать
+
+:::warning
+Это мой субъективный опыт, возможно он расходится с вашим. В этом случае вы можете или доработать данную статью или разместить свою рядом.
+:::
+
+Ответ простой, тестируем то что дорабатываем. Начинайте с интеграционных (компонентных) тестов вашей задачи которые проверяют основные кейсы по задаче.
+
+В процессе написания тестов не требуется учитывать все возможные сценарии поведения программы. Рекомендуется сосредоточиться на ключевых задачах, а остальные вносить (дополнять) по мере необходимости.
+
+Идеальный подход:
+
+1. На основании технического задания необходимо выделить тест-кейсы.
+2. Написать тесты реализующие эти кейсы, чаще всего это будут компонентные (интеграционные) тесты.
+3. Реализовать функциональность задания.
+4. При реализации добавляем новые тест-кейсы для упущенных и сложных моментов.
+5. Добиваемся зеленого прохождения тестов.
+6. Проверяем задачу вручную.
+7. Задаем задачу.
+
+## Провокация: пишите компонентные тесты, а не unit тесты
+
+Заголовок выше противоречит основной мысли из многих современных книг и учебников. Компонентные тесты гораздо дольше выполняются и при этом не показывают четкое место поломки кода. Несмотря на это, мы говорим о них как об “оплоте стабильности”. Дело в том, что для качественного покрытия unit тестами требуется гораздо больше времени, чем для написания хорошего компонентного теста. Хорошее покрытие unit тестами не гарантирует вам правильность взаимодействия классов между собой. И это крайне дорогое удовольствие. На их разработку и поддержку требуется очень много времени. В реальном проекте программисту, как правило, не выделяют время на написание unit тестов. Получается, что если на проекте выбрана именно политика unit тестов, то эти тесты не отражают реальные сценарии использования приложения - проверяется “сферический конь в вакууме”, причем не во всех возможных состояниях системы. В итоге такая политика разработки тестов рано или поздно приводит к тому, что тесты перестают защищать от дефектов приложения.
+
+[Источник](https://habr.com/ru/companies/axenix/articles/724318/)

documentation/docs/cook-book/recommendations/why-xunit.md → documentation/docs/recommendations/why-xunit.md

@@ -11,6 +11,10 @@ sidebar_position: 0
 
 Существует несколько причин использования модульных тестов.
 
+<div style={{textAlign: 'center'}}>
+![image](images/amongus.png)
+</div>
+
 ## Сокращение времени функционального тестирования
 
 Функциональные (сценарные) тесты требуют значительных ресурсов. Обычно они включают запуск приложения и выполнение ряда шагов, которые вам (или другому сотруднику) необходимо пройти для проверки ожидаемого поведения. Тестировщик не всегда может знать все необходимые действия, и в таких случаях ему может понадобиться помощь более опытного коллеги. Время тестирования варьируется: оно может занять всего несколько секунд при проверке небольших изменений или растянуться на несколько минут при более крупных изменениях. Этот процесс нужно повторять при каждом внесении изменений в систему.
@@ -47,6 +51,10 @@ sidebar_position: 0
 
 **Соизмеримый**: Написание юнит-теста не должно занимать непропорционально много времени по сравнению с тестируемым кодом. Если написание тестов занимает значительно больше времени, чем написание самого кода, следует рассмотреть более удобный для тестирования дизайн решения.
 
+**Устойчивость к рефакторингу**: Тесты должны быть устойчивы к рефакторингу кода. Если производится рефакторинг, тесты не должны изменяться. Тогда успешное завершения всех модульных тестов после этапа рефакторинга поможет вам убедиться, что рефакторинг не испортил функционал приложения.
+
+**Простота поддержки**: Тесты должны быть просты в поддержке. Этот пункт выполняется, если выполняется предыдущий пункт. Должно быть легко добавлять новые тестовые сценарии - поддержка тестов в актуальном состоянии не должна стать тяжелым грузом для команды разработки.
+
 ## Кодовое покрытие
 
 Высокий процент кодового покрытия часто ассоциируется с более высоким качеством кода. Однако само измерение не может определить качество кода. Установка слишком амбициозной цели по проценту кодового покрытия может оказаться контрпродуктивной. Представьте сложный проект с тысячами условных ветвлений и целью в 95% покрытия кода. Если в настоящее время проект поддерживает 90% покрытия, то затраты времени на учёт всех крайних случаев в оставшихся 5% могут оказаться огромными, а ценность этого может быстро снизиться.