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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Принцип построения "грозовых туч"

Сразу скажу - в этой заметке ничего о тестировании не будет, так как это просто подготовка почвы, выкладка теории и ничего больше

Выдержка будет вольным пересказом из книжки "Цель-2" Элияху Голдратта.

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

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

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

А потом соединяем противостоящие друг другу положения с общей целью. И далее мы вытаскиваем на поверхность исходные посылки и оспариваем их правильность.

Пример - дочка Шэрон хочет пойти на вечеринку, которая закончится поздно вечером. Папа против. Он решает нарисовать "грозовую тучу".

1. В правом верхнем углу пишет ответ на вопрос "Чего хочу я?" - "Шэрон дома до 10".
2. Ниже записывает ответ на вопрос "Что хочет Шэрон?" - "Шэрон дома около 12".
3. Почему я хочу, чтобы Шэрон была дома до 10? Тут происходит мозговой штурм и откидываются все нелепые ответы. "Я забочусь о ее репутации". Да брось, чем это повредит ее репутации? Главная сложность этапа - правильно обосновать свое "хочу".
4. Почему дочка хочет вернуться поздно? Чтобы быть популярной. А какая популярность, если родители на тусовки не пускают?
5. Итак, а какова наша общая цель? Чувствовать себя в семье хорошо.

Туча построена.

С ней отец приходит к дочери и они вместе выискивают исходные посылки и пытаются их опровергнуть. Почему, для того, чтобы обеспечить безопасность дочери, ей надо быть дома рано? Это плавно выливается в глазки из Шрека и просьбу дочки:

- Па-а-ап, а может быть, ты меня встретишь после вечеринки?

Вот и все, проблема решена! А ведь можно было обидеться друг на друга и запереться в разных комнатах "Да как он не понимает!" - "Да как она не понимает!".

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

Вот, кстати, хорошая ссылочка на грозовую тучу.

Итого, для построения "грозой тучи":

• Первый шаг - четко сформулировать суть конфликта.
• Второй шаг - вытащить на поверхность исходные посылки и оспорить их правильность