Где писать описание автотестам, в вики или коде?

Итак. Есть код - автотесты. Аккуратно разложенные по папочкам, структурированные и отчасти даже с говорящими именами, по которым все понимаешь без описания.

Тестов много. Можно в каждом писать комментарий, что этот тест покрывает. Но - неудобно. Не видно картины в целом.

И есть вики. Там тесты отображены в виде чек-листов, то есть не длинные утомительные описания, а небольшая табличка - название в коде, краткое описание и ожидаемый результат.

Очень симпатичные описания. Позволяют увидеть всю картину. Та-а-а-ак, а есть ли у нас тесты на функцию А? Открываем документацию и читаем полный набор тестов. Это позитивнее, чем заходить внутрь каждого теста и читать комментарий.

С другой стороны, если бы сам тест был простым (а не состоящим из нескольких таблиц), то можно было бы сделать один баааальшой тест, куда запихать все остальные, относящиеся к данной функции, и у каждой строки (1 строка = 1 тест) сделать комментарий.

Удобно? Да. Только для сложных функций в таком виде сам тест становится нечитаемым.

Что получается? Получается грозовая туча.

Какие у нас есть исходные посылки?

• Постоянно переключаться код / описание в вики неудобно => Тесты надо писать в коде, чтобы все хранилось в одном месте.
• Неудобно переключаться код (описание теста) / требования при анализе, какие тесты на эти требования есть => Описания тестов и описание требований тоже должны быть в одном месте. то есть в вики, в коде как-то неудобно требования дублировать.

Как разбить грозовую тучу?

Надо оспорить их правильность. Так ли уж сложно переключаться между кодом и вики? Все равно ведь требования в вики и ты туда все равно переключаешься...

Может, просто открывать не 20 закладок, а всего парочку - одна на требования, вторая на тесты? Правда, они потихоньку вырастут, но не во много раз.

А если наоборот? Неужели сложно переключаться с требований на код - ведь все равно во время ревью теста тебе надо открыть тест, там и комментарий прочитаешь. Хм. общий взгляд? Можно вытащить все-все-все комментарии в отдельный файлик кода (автоматически, само собой). Тогда ты будешь переключаться между файликами в коде, чтобы получить полную картину и чтобы увидеть частный случай.

Хотя - так ведь можно сгенерировать отчетик, который будет ссылками на тесты! Есть в тесте bean (Spring framework), в отчете у нас примерно такая структура, табличка с 3 колонками:

• Название теста (ссылка на его bean).
• Краткое описание.
• Результат (тоже кратко).

Итого мы имеем - в каждом коде свой коммент описания и свой коммент результата.
Общая картина в коде - в отдельном файле, на уровне общих для всех тестов параметров.
Ну и последний аккорд - этот самый отдельный файл синхронизируется с вики, заполняя ее, разве что без ссылок.

Все счастливы и все довольны. Хочешь - в коде открой страницу с тестами и почитай, чтобы понять, надо ли тебе что-то добавить в связи с улучшением функции.

Хочешь - забей на вики и работай в коде - тут тебе и общий взгляд, и отдельные комментарии.

Круто? По-моему, вполне

Но посмотрите - мы сейчас определили только одну проблему - неудобство переключения между вики и кодом. Однако этот подход не решает проблемы, когда нет смысла переключаться, так как есть еще вторая проблема - лень и / или забывчивость.

Ведь если не заполнять комментарий к тесту, то и ничего не сгенерится и ты ни в википедии, ни в коде не найдешь описания, только сам тест.

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

Такое вот решение, как мне кажется, удовлетворяющее в данном случае всех.