Работать со спецификациями программного обеспечения сложно. Неважно, в каком именно поле; Вы сталкиваетесь с большим вопросом: все ли указанное когда-либо реализовано и протестировано? Еще во времена методологий, ориентированных на водопад, это было проблемой, и даже сегодня, во время написания, гибкость и пользовательские истории все еще не гарантируют вам идеальной подгонки. Многие из современных гибких подходов хорошо сочетаются с разработкой, управляемой тестами, или даже с концепциями, ориентированными на поведение, чтобы перевернуть проблему с ног на голову. Вместо того чтобы задавать вопрос «Охватывает ли мой код каждое предложение письменной спецификации?» они просто предполагают, что написание тестов в первую очередь является правильным способом получения необходимого покрытия. Недостатком здесь является отсутствие документации, которая легко может произойти. Кроме того, вы никогда не найдете подходящий рабочий процесс для перефакторинга тестов на один документ. То, что может работать для отдельных решений и проектов, подходит к концу, если вы посмотрите на такие вещи, как «Комплекты совместимости технологий» (TCK), которые по своей природе более или менее собраны из любого вида письменной спецификации на основе документа.
TCK для платформ Java
Погружение в подобные темы всегда является хорошим кандидатом для поляризации сообщества разработчиков. Тем более, что документация по-прежнему остается темой, которая обычно полностью забывается или откладывается. Для меня документация является ключевой для майских уровней. На уровне фреймворка это гарантирует, что ваши пользователи не борются, а вы закладываете хорошую основу для быстрого принятия. Для меня проект и команда Arquillian в первые годы сделали потрясающую работу. Даже на уровне проекта имеет смысл быстро обмениваться новыми членами команды без потери знаний. Но есть еще одна область, которая не просто извлекает выгоду из этого, но имеет сильное отношение к документации: TCK Java. Все платформы Java определяют запросы спецификации Java (JSR) в качестве точки для улучшения языка. Комплект для обеспечения совместимости технологий (TCK) — это набор тестов, который по крайней мере номинально проверяет конкретную предполагаемую реализацию запроса спецификации Java (JSR) на соответствие. Принимая во внимание тот факт, что большинство спецификаций существуют в некоторых документах, подобных Office, и передаются в виде PDF-файлов для просмотра и комментариев, почти невозможно сказать, что TCK вообще имеет определенный охват исходной спецификации. В лучшем случае это страшно. Большую часть времени это раздражает, потому что ссылочные реализации (RI) просто забывают охватить части спецификации, и пользователь должен обрабатывать возникающие ошибки или поведение определенным образом. Если это вообще возможно.
Просто короткое замечание о наличии TCK. Большинство из них не доступны на сегодняшний день, но на них распространяются условия лицензионных и финансовых соглашений. Надеюсь, это изменится с предстоящими изменениями в процессе сообщества Java.
Некоторые JBoss Goddess для лечения документации
Но некоторые светлые умы нашли решение. Вероятно, это не является большим сюрпризом, что большие усилия были сделаны парой RedHats. Небольшой проект, который изначально был создан как часть проекта hibernate-validator, который является RI для BeanValidation, предназначен для решения проблем. Неизвестный и сам по себе недокументированный проект jboss-test-аудит называет себя «служебными классами для отчета об охвате тестов TCK». Это прекрасно пригвоздит это. Это очень легкое, но все же мощное небольшое дополнение к любому RI, которое обрабатывает источники для специальных аннотаций для сбора отчета о покрытии для любого проекта, целью которого является реализация спецификации. Он лицензирован под лицензией Apache, версия 2.0, и вам нужно всего лишь несколько шагов, чтобы запустить его в соответствии с вашими настройками. Все начинается со спецификации. Это документ XML, который определяет различные разделы и необходимые утверждения.
|
1
2
3
4
5
6
|
<specification> <section id="1" title="Chapter 1 - Introduction"/> <section id ="2" title="Chapter 2 - What's new"> <assertion id="a"> <text>A simple sample test</text> </assertion> |
|
1
|
</section> |
|
1
|
</specification> |
Этот документ является базовой линией для ваших тестов. Теперь вам нужно пойти дальше и снабдить все свои тесты соответствующим разделом и информацией об утверждениях. Это может выглядеть следующим образом:
|
1
2
3
4
5
6
7
8
9
|
SpecVersion(spec = "spectests", version = "1.0.0")public class AppTest { @Test @SpecAssertion(section = "2", id = "a") public void simpleTestForAssertion() { App app = new App(); assertEquals(app.sayHello("Markus"), "Hello Markus"); } |
В сочетании с небольшим количеством волшебства maven (maven-processor-plugin) все аннотации анализируются, и генерируется хороший отчет об общем покрытии. Если вы хотите ознакомиться с полным примером начальной загрузки, найдите его на github.com/myfear .
Твердые части
Это, очевидно, ежу понятно. Добавление некоторых аннотаций к вашим тестам не будет самой сложной вещью, которую вы когда-либо делали. Что действительно сложно, так это преобразовать вашу документацию в этот необычный формат аудита xml. Есть много способов сделать это. Учитывая тот факт, что большинство компаний, возглавляющих JSR, располагают каким-то жестким управлением документооборотом, это должно быть реализовано один раз в жизни. Если вы работаете с Microsoft Word, вы также можете использовать имеющуюся XML-схему для написания правильно оформленных документов (что очень неудобно! Не делайте этого!).
Множество идей
Маленькие вспомогательные классы работают сравнительно хорошо. Но есть еще много возможностей для улучшений. Это может быть правильной идеей иметь здесь некоторую вспомогательную информацию, такую как номера выпусков или другие ссылки. Я также хотел бы иметь возможность использовать asciidoc в документации. Но я не жалуюсь здесь, потому что я не собираюсь менять это сам. Но если кому-то интересно, все это можно найти на github.com, и я думаю, что эти парни знают, как работает сообщество, и принимают вклады.
Будущие пожелания для JCP
Принимая во внимание этот простой и легкий подход, было бы хорошо стимулировать принятие вместе с JSR. Поэтому, если вам это нравится, обратитесь к члену Еврокомиссии, которому вы доверяете, и сообщите ему об этом и включите в список идей.