Как автоматизировать тестирование документации: решения от SDET-инженера

Часто QA-специалисты фокусируются на функциональности, а документацию могут оставлять без должного внимания. На первый взгляд это кажется логичным: продукт работает — и хорошо. Но если пользователи не смогут разобраться с руководством, то возрастет число обращений в техподдержку и снизится уровень удовлетворенности клиентов. А мелочи вроде опечаток, на которые закрывали глаза, могут негативно повлиять на репутацию бренда. Как решить типичные проблемы с качеством документации и ее локализации через внедрение автотестов? Своим опытом делится в статье SDET-инженер Test IT Андрей Черных. 

Зачем тестировать документацию

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

• Битые ссылки. Появляются, например, когда в документации сохраняется референс на функциональность, которую уже давно изменили.
• Пустые или разные ключи JSON в разных локализациях. Проблемы появляются при неполном переводе или при обновлении только одной языковой версии.
• Кириллица в английской локализации. Частая ошибка, например, когда забыли переключить раскладку. 
• Неправильная кодировка файлов. MD-файлы могут преобразовываться в HTML и поломаться, если утилита не распознает кодировку, либо символы на сайте будут отображаться некорректно.
• Ошибки в названии бренда и опечатки. Даже если смысл понятен, общее впечатление от документации портится.

Как с этим справляться? На мой взгляд, есть несколько решений. 

✅ Привлечь команду. Паблишеров для работы с локализацией и техписателей документации. Подходящий вариант для крупных компаний, но для бизнеса поменьше это может быть слишком затратно.

✅ Переложить задачи на одного сотрудника. Распространенное, но рискованное решение. Человек просто не успевает держать все под контролем, из-за чего пострадает качество.

✅ Внедрить автоматизированные тесты. Заголовки, списки, кодировки, доступность ссылок, анализ текста на мелкие ошибки — все это можно проверить автоматически.  

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

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

Инструментарий

Передо мной стояла задача — написать локализационные тесты для документации и сделать понятный для технического писателя вывод результатов. 

Для этого требовалось подобрать инструментарий. Выбор пал на эти инструменты:

✅ Python. Он подходит для множества задач благодаря большому количеству библиотек и простоте использования. Я его выбрал как основный язык программирования, также использовал для поиска битых ссылок и проверки кодировки файлов. 

✅ Pytest. Тестовый фреймворк легко настраивается с другими библиотеками и позволяет быстро писать тесты.

✅ Deepdiff. Утилита сравнивает JSON, показывая новые ключи, отсутствующие или пустые.

✅ Language_tool_python. Анализатор текста находит орфографические и пунктуационные ошибки, проверяет лишние пробелы, кодировку и другое.

✅ Свои алгоритмы для проверки MD-разметки. Потребовались, так как готовые библиотеки для преобразования текста в Markdown не справлялись с особенностями технической документации, например, не понимали, что звездочка может быть частью кода, а не элементом разметки.

✅ Test IT и Pytest-HTML для формирования отчетов. Pytest-HTML создает веб-отчеты для быстрого анализа тестов. А уже в системе управления тестированием можно детально работать с этими данными, отслеживать историю и строить дашборды. 

Для передачи данных в Test IT удобнее всего использовать адаптер для Pytest, который отправляет результаты автотестов напрямую в систему. О том, как подключать адаптеры, читайте по ссылке.

Первые результаты автотестов

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

1. Проверки MD-файлов оказались неэффективными

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

2. Инструменты нестабильно работали с технической документацией

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

3. Проверялось сразу множество файлов

При первой реализации я выбрал неудачное решение и одновременно загружал множество файлов вместо того, чтобы проверять каждый файл по отдельности. Эта ошибка повлияла на формирование отчетности. Система создавала длинный список ошибок, что было крайне неудобно и малоинформативно.

Вторая итерация: что и как улучшил 

Решил проблему с MD-разметками. После консультации с техническим писателем я полностью выкинул излишние MD-проверки. Система сразу задышала легче. 

Создал два словаря. Для того чтобы стабилизировать работу анализатора тестов, придумали сделать специальный словарь терминов. С помощью автоматизированной утилиты мы собрали все специфичные слова, разделили на действительно ошибочные и профессиональные термины. Первые внесли в JSON для тестов, а вторые согласовываем с техписом.

Стабилизировал встроенные в Python инструменты для работы с кодировкой. Исходно было требование использовать кодировку UTF-8. В первой версии я проверял, чтобы все файлы были в UTF-8. Однако возникали проблемы, так как анализаторы иногда ошибочно определяли кодировку. Например, они могли указать, что файл в кодировке ASCII, хотя это не являлось проблемой, так как ASCII — это подмножество UTF-8. Тем не менее, такие ошибки приводили к сбоям.

Мы устранили эти проблемы, в том числе с редиректорами. В Python это решается просто: указываешь заголовок и проверяешь код ответа, чтобы убедиться, что все работает правильно. После этого изменения были внедрены в пайплайны, и мы добавили механизм блокировки MR, если тесты не проходят.

Итого: после всех манипуляций мы вышли на стабильный результат — 1855 успешных тестов.

Поддержка проверки качества максимально простая. Раз в неделю-две мы заходим в файл с правилами в формате JSON, добавляем туда нужное слово-исключение.

Примеры валидных слов, которые используются в Jira и других системах, но анализатор текста их не понимает:

Итоги

Автоматизированные тесты помогают поддерживать документацию в хорошем состоянии и исправлять существующие баги. Пользователи реже сталкиваются с ошибками, 404-ми страницами. 

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

Автоматические проверки не допускают ошибок при объединении изменений в документацию. Например, если кто-то случайно удалит JSON-файл, который используется в других частях документации, пайплайн не пропустит такой мердж.  

Полное представление о результатах тестирования для нас генерирует система управления тестированием Test IT. Мы с командой видим все важные данные, включая причины падений тестов и шаги, которые привели к этим падениям.

Ключевые выводы

• Автоматизация тестирования документации помогает минимизировать ошибки и снять нагрузку с команды.

• Внедрить автотесты могут компании разных масштабов, миксуя их с целыми отделами или разгружая специалиста в небольшой компании, на котором держится все. При этом поддержка автотестов требует минимальных усилий.

• При внедрении важно учитывать, что не все инструменты будут идеально выполнять свою работу. Нужно анализировать и стабилизировать их.

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

Оцените возможности Test IT прямо сейчас на бесплатном тарифе