Митап Testify #8: Качество вопреки хаосу 5 декабря в 18:00

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

515

Часто 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. Проверялось сразу множество файлов

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

Скриншот системы Test IT. Отчет наглядный, но неинформативный

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

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

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

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

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

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

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

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

Итоги

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

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

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

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

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

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

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

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

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


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

Была ли статья полезной?