Документация модульного теста [закрывается]
Я хотел бы знать от тех, кто документирует модульные тесты, как они документируют его. Я понимаю, что большинство подписчиков TDD утверждает, что "код говорит", и таким образом документация по тестированию не очень важна, потому что код должен быть самодокументированным. Достаточно ярмарка, но я хотел бы знать, как зарегистрировать модульные тесты, не, зарегистрировать ли их вообще.
Мой опыт как разработчик говорит мне, что понимание старого кода (это включает модульные тесты) является трудным.
Таким образом, что важно в документации по тестированию? Когда имя метода тестирования не является достаточно описательным так, чтобы документация была выровнена по ширине?
5 ответов
В соответствии с просьбой Торстена79, я подробно расскажу о своих комментариях в качестве ответа. Моим оригинальным комментарием было:
"Код говорит", к сожалению. совершенно неправильно, потому что не разработчик не может прочитать код, пока он хотя бы частично умеет читать и понимать генерируемый документацию, и таким образом он может знают, какие тесты проверяют. Это особенно важно в тех случаях, когда клиент полностью понимает домен и просто не может прочитать код, и становится ещё более важным, когда устройство тесты также тестируют аппаратное обеспечение, как и в встроенный мир, потому что тогда ты проверяешь вещи, которые можно увидеть.
Когда вы делаете модульные тесты, вы должны знать, пишете ли вы их только для себя (или для своих коллег), или пишете ли вы их и для других людей. Во многих случаях вы должны писать код для своих читателей , а не для вашего удобства.
При смешанной разработке аппаратного/программного обеспечения, как в моей компании, клиенты знают, чего они хотят. Если их полевое устройство должно выполнить сброс при получении определенной команды по шине, то должен быть выполнен юнит-тест, который посылает эту команду и проверяет, было ли устройство сброшено. Мы делаем это прямо сейчас с NUnit в качестве фреймворка юнит-тестов, а также с некоторым пользовательским программным и аппаратным обеспечением, которое делает возможным отправку и получение команд (и даже нажатие кнопок). Это здорово, потому что единственная альтернатива - это делать всё это вручную.
Клиент абсолютно точно хочет знать, какие тесты существуют, и даже хочет провести их самостоятельно. Если тесты не документированы должным образом, он не знает, что делает тест, и не может проверить, все ли тесты, которые, как он думает, ему понадобятся, и при запуске теста он не знает, что он будет делать. Потому что он не может прочитать код. Он знает используемую шинную систему лучше, чем наши разработчики, но они просто не могут прочитать код. Если тест провалится, он не знает почему и даже не может сказать, что, по его мнению, должен сделать тест. Это нехорошо.
Документально задокументировав юнит-тесты, мы имеем
- -кодовую документацию для разработчиков
- -тестовую документацию для заказчика, которая может быть использована для доказательства того, что устройство делает то, что оно должно делать, т.е. то, что заказчик заказал
- -способность генерировать документацию в любом формате, которая может быть даже передана другим участвующим сторонам, например, производителю
- правильно в данном контексте означает: Написать понятный язык, который может быть понятен не разработчикам. Вы можете оставаться техническим, но не писать вещи, которые только вы можете понять. Последнее, конечно, важно и для любых других комментариев и любого кода.
Независимо от нашей конкретной ситуации, я думаю, что это то, чего бы я хотел в юнит-тестах все время, даже если это чистое программное обеспечение. Клиент может игнорировать юнит-тесты, о которых он не заботится, как и тесты основных функций. Но просто иметь там докторов никогда не повредит.
Как я написал в комментарии к другому ответу: Кроме того, сгенерированная документация также является хорошей отправной точкой, если вы (или ваш босс, или коллега, или отдел тестирования) хотите изучить, какие тесты есть и что они делают, потому что вы можете просматривать их, не копаясь в коде.
В самом тестовом коде:
С комментариями уровня метода, объясняющими , что тестирует / покрывает.
На уровне класса комментарий, указывающий на фактический тестируемый класс (который фактически может быть выведен из имени тестового класса, поэтому на самом деле это менее важно, чем комментарии на уровне метода).
С отчетами о тестовом покрытии
- Например, Cobertura . Это тоже документация, поскольку в ней указывается, что покрывают ваши тесты, а что нет.
Когда я вернусь на старом тесте и не понимаю его сразу
- Я рефакторирую, если возможно
- , или пишу тот комментарий, который заставил бы меня сразу понять его
Когда вы пишете свои тестовые примеры, это то же самое, что вы пишете свой код, вам все предельно ясно. Это затрудняет представление о том, что вам следует написать, чтобы сделать код более понятным.
Обратите внимание, что это не означает, что я никогда не пишу никаких комментариев . По-прежнему существует множество ситуаций, когда я просто знаю, что мне будет трудно понять, что делает конкретный фрагмент кода.
В таких ситуациях я обычно начинаю с пункта 1 ...
Улучшение модульных тестов как исполняемых спецификаций является целью Behavior-Driven Development : BDD - это эволюция TDD, где модульные тесты используют универсальный язык (язык, основанный на бизнес-домен, совместно используемый разработчиками и заинтересованными сторонами) и выразительные имена ( testCannotCreateDuplicateEntry ) для описания того, что должен делать код. Некоторые фреймворки BDD зашли очень далеко и показывают исполняемый файл, написанный почти на естественном языке, например .
При необходимости комментируйте сложные тесты или сценарии, но в первую очередь отдайте предпочтение читаемым тестам .
С другой стороны, я стараюсь, чтобы мои тесты говорили сами за себя. Другими словами:
[Test]
public void person_should_say_hello() {
// Arrange.
var person = new Person();
// Act.
string result = person.SayHello();
// Assert.
Assert.AreEqual("Hello", result, "Person did not say hello");
}
Если бы я взглянул на этот тест, я бы увидел, что он использует Person (хотя он был бы в PersonTest.cs в качестве подсказки;)), тогда, если что-то сломается, оно будет встречаются в методе SayHello . Сообщение assert также полезно не только для чтения тестов, но и при запуске тестов их легче увидеть в графическом интерфейсе.
Следуя стилю AAA Arrange, Act и Assert, тест по существу документирует сам. Если бы этот тест был более сложным, вы могли бы добавить комментарии над тестовой функцией, объясняющие, что происходит. Как всегда, вы должны постоянно обновлять их.
В качестве примечания, использование нотации подчеркивания для имен тестов делает их более читаемыми, сравните это с:
public void PersonShouldSayHello()
Что для длинных имен методов может затруднить чтение теста. Хотя этот момент часто бывает субъективным.