Тестирование api

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

Его появлению предшествовало 15 лет практики тестирования в компании IBS AppLine* (лидера российского рынка аутсорсинга услуг тестирования по версии TAdviser за 2018 год на минуточку!). На базе этих знаний и экспертизы мы задались целью ускорить старт проектов, повысить качество тестирования, упростить введение в работу новичков. Решение должно позволить автоматизировать функциональное тестирование веб, мобильных, десктоп-приложений и различных видов API.

В общем, исследовательский центр IBS AppLine Innovation** суммировал весь опыт компании и создал Хамелеон инструмент для автоматизации функционального тестирования. Делался с использованием языка программирования Java и инструментов Cucucmber, Selenium, Appium, Winium, Spring. Этот фреймворк:

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

Теперь подробнее о функционале

Как устроен Хамелеон

Вот несколько особенностей нашего фреймворка:

• Это многомодульный maven-проект, который включает модули тестирования web, мобильных приложений, SAP-приложений, баз данных, Rest API и web-сервисов. Необходимые модули подключаются к проекту.
• Мы взяли проверенные временем оpen source-инструменты, в том числе Selenium, Appium, Winium, и удачно их объединили в одном решении.
• Для ускорения разработки автоматизированных тестов мы создали плагин для среды разработки IntelliJ IDEA. Получился полезный инструмент разработчика автоматизированных тестов. Плагин дополняет возможности IDEA, делая ее полноценным рабочим местом.
• Для удобства разработки автоматизированных тестов для web-приложений мы создали расширение для браузера Google Chrome, которое позволяет добавлять элементы тестируемого приложения в проект прямо из браузера и имеет возможность записи автоматизированного теста в формате Cucumber методом Record&Playback.

Open source-библиотеки

В основе инструмента лежат оpen source-библиотеки Selenium, Appium, Winium, UIAutomation. Для разработки самих тестов используется фреймворк Cucumber, который позволяет писать на русском языке. Такой формат понятен и ручным тестировщикам, и не имеющим отношения к написанию конкретного теста специалистам автоматического тестирования, что снижает порог вхождения сотрудников в проект. Всему, что происходит в Cucumber, соответствуют свои Java-команды, так что при необходимости тесты можно разрабатывать на чистой Java.

Простота установки

Для разработки автоматизированных тестов с использованием Java на рабочую станцию устанавливаются Java JDK, Apache Maven/Gradle, IntelliJ IDEA, плагины для Intellij IDEA, Git Client. У начинающих специалистов это занимает много времени. Мы упростили процесс, разработав общий инсталлятор, который представляет собой .exe-файл с возможностью выбора необходимого ПО для установки на рабочее место:

Начало разработки

Для разработки автоматизированных тестов можно использовать готовые стартеры проектов. Стартеры это архетипы maven, которые содержат готовую структуру проекта. Они хранятся во внутреннем репозитории компании. При создании проекта в IntelliJ IDEA нужно лишь выбрать необходимые. Например, для разработки тестов, которые взаимодействуют с web-приложением и REST, необходимо подключить модули chameleon-selenium-cucumber и chameleon-rest-cucumber.

Немного о фреймворке

В основном автоматизированные тесты разрабатываются с помощью инструмента Cucumber, который позволяет писать тесты на русском языке. Автоматизированный тест состоит из следующих блоков:

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

Пример автоматизированного теста:

# language: ru# Тестовые данные:  # $ФИО Иванов Иван Иванович  # $ссылка https://www.appline.ru/Функция: Заявка на обучение  Сценарий: Заявка на обучение    * страница "Главная" загружена    * выбран элемент коллекции "Меню" с параметрами:      | field        | operator | value             |      | Наименование | равно    | Start IBS AppLine |    * нажатием на кнопку "Наименование" загружена страница "Start IBS AppLine"    * поле "Имя" заполняется значением "#{ФИО}"    * поле "Ссылка на резюме" заполняется значением "#{ссылка}"    * выполнено нажатие на "Отправить"    * поле "Required field" видимо

Существуют шаблоны для работы с переменными: операции с датами, математические операции, выполнение кода и т.д. Например, для работы с текущей датой используется шаблон #now{дата; исходный_формат; смещение}. Предположим, в автоматизированном тесте необходимо проверить дату операции, которая была только что осуществлена. Такая проверка будет выглядеть так:

* значение поля "Дата операции" равно "#now{dd.MM.yyyy HH:mm}"

А, например, создать отложенную операцию, которая исполнится завтра:

* поле "Дата операции" заполняется значением "#now{dd.MM.yyyy;+1d}}"

Выполнить программный код можно с использованием шаблона #script{RESULT=выражение_java}. Например, удаление лишних символов в переменной будет выглядеть следующим образом:

* в переменной "Номер_счета" сохранено значение поля "Номер счета"* значение поля "Номер счета" равно "#script{RESULT = Номер_счета.replaceAll("", "")}"

В нашем фреймворке разработаны основные Cucumber-шаги, которые напоминают шаги из ручных тестовых сценариев. Они описывают действия, которые человек может совершить с тестируемым приложением: нажать на элемент, ввести значение в поле, прочитать значение, сравнить значения и т.д. Таких шагов примерно 30. Для часто повторяемых операций такие шаги объединяются в более крупный шаг.

Например, авторизация в приложении может описываться в 3 шага:

Когда заполняются поля:  | field  | value        |  | Логин  | test@test.ru |  | Пароль | 123123       |И выполнено нажатие на "Войти"Тогда страница "Главная" загружена

Или на основе этих шагов создается 1 шаг (пароль в этом случае хранится в отдельном файле с пользователями):

Дано авторизован пользователь "test@test.ru"

Все размеченные элементы тестируемого приложения имеют свой тип, например, Button, TextInput, Combobox, Checkbox и т.д., это позволяет использовать одни и те же Cucumber-шаги для работы с разными типами элементов. Например, есть шаг:

* поле "field" заполяется значением "value"

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

АРМ тестировщика или разработка теста

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

• список тестов,
• объектный репозиторий,
• список доступных действий,
• настройки запуска,
• документацию,
• различные автокомплиты, ускоряющие процесс создания теста.

Список тестов

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

Репозиторий объектов

Традиционный и очень популярный инструмент разработчика автоматизированных тестов шаблон Page Object Pattern. При его использовании элементы тестируемого приложения описываются в отдельных java-классах, которые соответствуют страницам тестируемого приложения. На крупных проектах таких Page Object-классов становится очень много. Кроме того, иногда они еще и называются беспорядочно. В результате для больших проектов такой подход не очень удобен: неизбежно дублирование работы на проектах работает много специалистов, приходится расшифровывать работу коллег и анализировать разметку элементов, а это не всегда проходит гладко.

Поэтому мы создали репозиторий объектов тестируемого приложения. Он хранит все его элементы не в классах, а в одном или нескольких xml-файлах, а плагин для IntelliJ Idea показывает эти xml-файлы в виде древовидной структуры, в которой узлами являются страницы тестируемого приложения. Вместо разномастных английских названий мы используем русский язык, что упрощает работу тестировщиков, так им легче находить размеченные страницы и элементы, а также добавлять новые.

Приведем конкретный пример. Для одного крупнейшего отечественного банка (название по понятным причинам не называем) нами было разработано 20 автотестов, использовавших 78 страниц тестируемых приложений (достаточно длинный бизнес-процесс). В обычных условиях тестировщикам пришлось бы создать 78 java-классов и разметить на них более 2000 элементов. С Хамелеоном мы всю эту громаду открываем в древовидной структуре, в которой их легко и просто просматривать, перетаскивать, компоновать.

Существует два способа добавления элементов в репозиторий.

Добавление в среде разработки IntelliJ IDEA:

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

Также есть возможность добавлять элементы прямо из тестируемого приложения с помощью созданного нами расширения для браузера Google Chrome. Расширение самостоятельно определяет тип элемента, его наименование и подставляет локатор. Для этого достаточно навести мышкой на элемент. Расширение синхронизируется с плагином в IntelliJ IDEA, поэтому все, что происходит в браузере, передается в среду разработки. Так можно наполнять репозиторий объектов, проходя ручной тест в браузере. С помощью расширения можно проверить корректность локатора уже существующего в репозитории элемента.

Чтобы не было дублирования элементов, существует тип элемента Block. Например, у нас в тестируемом приложении есть блок Меню, и он доступен на всех страницах приложения: в этом случае в репозитории элементов мы размечаем его как страницу Меню, содержащую элементы меню, а на других страницах добавляем его как элемент с типом Block. Таким образом, получается переиспользование элементов, которые встречаются более чем на одной странице.

Разработка автоматизированного теста

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

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

При этом доступны подсказки не только для списка возможных шагов, но и для элементов, которые могут участвовать в выбранном действии. Плагин определяет страницу (контекст) и предлагает элементы из репозитория объектов или переменные для сucumber-шага, которые относятся к выбранной странице. Это исключает возможность ошибки при использовании еще не размеченного элемента страницы и ускоряет процесс разработки теста.

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

Третий способ разработки автотеста (самый удобный и популярный) с помощью нашего расширения для браузера Google Chrome. Плагин записывает действия пользователя на странице тестируемого приложения и конвертирует их в автоматизированный тест.

Например, пользователь логинится на сайте, нажимая для этого на кнопку Логин. Рекордер записывает шаг * выполнено нажатие на поле Логин. Пользователь заполняет поле Логин значением User, рекордер записывает шаг * поле Логин заполняется значением User и так далее. После этого получившийся автотест можно скопировать и вставить в среду разработки для редактирования. Плагин автоматически, на основе объектного репозитория, определяет, на какой странице находится пользователь, и выполняет поиск размеченных элементов. Если элемента в репозитории нет, то будет предложено его добавить.

Пока рекордер существует только для браузера. В процессе разработки находится рекордер для SAP GUI.

Запуск и отладка

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

• подсветку элементов будут выделяться элементы, с которыми взаимодействует тест;
• запись видео в случае ошибки к отчету будет прикреплено видео прохождения автоматизированного теста;
• конфигурацию запуска браузер, в котором будет выполнен тест;
• режим запуска с графическим интерфейсом или headless-режиме (без графического интерфейса);
• закрытие браузера после теста удобно при разработке длинных тестов или локализации ошибок;
• подключение к открытому браузеру чтобы начать автоматизированный тест не с начала, а с выбранного места, подключаясь к открытому браузеру.

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

Чтобы отслеживать ход выполнения теста, мы разработали консоль, куда перенаправляется весь лог с IntelliJ IDEA. Это позволяет контролировать процесс и понимать, что сейчас выполняет автоматизированный тест. Консоль отображается поверх содержимого экрана и не мешает выполнению теста. Есть возможность настраивать формат вывода в консоль (размер, шрифт, цвет и т.д.).

Документация

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

Тестирование API

Для тестирования API (REST и SOAP) также используется объектный репозиторий. В этом случае страницами будут endpoint, а элементами заголовки и тело запроса.

Во фреймворке реализованы базовые действия с API, при наборе действий происходит автоподстановка параметров вызова.

Отчет о выполнении автоматизированных тестов

В качестве инструмента отчетности был выбран Allure. При запуске тестов из среды разработки IntelliJ IDEA аllure-отчет можно открыть прямо из плагина.

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

Результаты

Хамелеон помог нам не на словах, а на деле.

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

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

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

Наконец, мы получили еще одно преимущество на отечественном рынке: кодирование на русском языке легче освоить. Для этого у нас есть корпоративный университет, где мы обучаем будущих тестировщиков писать автотесты с нуля буквально за месяц. И в этом очень важную роль играет Хамелеон: с его помощью мы закладываем общую базу, на нем обязательно проводим несколько занятий по разработке тестов. Ежемесячно через этот курс проходит 5-10 человек, имеющих базовые знания языка программирования Java.

Планы на будущее

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

---

* IBS AppLine лидер российского рынка услуг тестирования и обеспечения качества программного обеспечения, разработчик решений для автоматизации тестирования. Компания была создана в 2001 году, в штате более 700 специалистов, общее количество проектов превысило 1500.

** IBS AppLine Innovation (ранее Аплана АйТи Инновации) была создана в декабре 2017 года как центр исследований и разработки компании IBS AppLine (ранее Аплана). Основу команды составили ее собственные опытные инженеры и разработчики.

Есть API, которые в целом как-то работают, но имеют проблемы с безопасностью, документацией или валидацией данных. Автор статьи объясняет, почему в современных реалиях это недопустимо, и даёт рекомендации по исправлению недостатков.



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

Когда API сервисы становятся публичными, чуда не происходит. Количество пользователей не растёт, а о том, чтобы сделать эту функциональность платной, вообще можно забыть (исключаем случаи, когда продукт раскручивают за счёт маркетинговой лжи с агрессивной рекламой).

А если от публичного API напрямую зависит доход компании, то ставки по-настоящему высоки. Эта мысль подробнее раскрыта в книге Непрерывное развитие API. Правильные решения в изменчивом технологическом ландшафте (Мехди Меджуи, Ронни Митра и др):


а мы пойдём дальше...

Разработчики могут быть в основном сосредоточены на том, чтобы в API была реализована вся запланированная функциональность. Но существуют нефункциональные требования, которые часто выполнены не в полной мере и требуют особого внимания.

На мой взгляд, для всех API обязательно качественное выполнение следующих нефункциональных требований:

• Безопасность
• Документация
• Валидация
• Тестирование

Безопасность

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

1. Использование HTTPS с SSL-сертификатами
2. Совместное использование ресурсов из разных источников (CORS)
3. Аутентификация и JSON Web Tokens
4. Авторизация и привилегии доступа
   
   

* Здесь и далее сузим контекст до REST и JSON API.

1. Использование HTTPS с SSL-сертификатами

Сейчас HTTPS с использованием SSL-сертификатов является де факто стандартом безопасности. Для генерации сертификатов лично я использую Let's Encrypt бесплатный, центр автоматизированный сертификации от некоммерческой организации Internet Security Research Group (ISRG).

Эти сертификаты гарантируют, что данные, идущие от вашего API к пользователю, будут зашифрованы.

2. Совместное использование ресурсов из разных источников (CORS)

Чтобы обеспечить безопасность запросов к другим источникам, браузеры используют механизм под названием CORS. Аббревиатура CORS расшифровывается как Cross-Origin Resource Sharing технология совместного использования ресурсов разных источников. Несмотря на то, что браузеры (в силу правила одинакового источника) не позволяют получать доступ к ресурсам из разных источников, CORS позволяет обойти эти ограничения и при этом быть уверенным, что доступ к ресурсам будет безопасным.

Пользовательские агенты (к примеру, браузеры) на основе значений дополнительных заголовков для CORS в HTTP-запросе могут выполнять запросы к другим источникам, которые без CORS были бы заблокированы.



Приведём пример:

HTML страница, обслуживаемая сервером с http://domain-a.com, запрашивает src по адресу http://domain-b.com/image.jpg .

Многие страницы загружают ресурсы вроде CSS-стилей, изображений и скриптов с разных доменов, соответствующих разным CDN (сетям доставки контента).

Сегодня достаточно популярна реализация CORS для Node.js.

3. Аутентификация и JSON Web Tokens (JWT)

Существует несколько подходов к аутентификации пользователя API, но один из лучших это использование JWT. Эти токены подписываются с использованием различных криптографических алгоритмов.

JSON Web Token это открытый стандарт для создания токенов доступа, основанный на формате JSON. Как правило, используется для передачи данных для аутентификации в клиент-серверных приложениях.

Для создания токена необходимо определить заголовок (header) с общей информацией по токену, полезные данные (payload), такие как id пользователя, его роль и так далее, а также подписи (signature). Простыми словами, JWT это лишь строка в следующем формате header.payload.signature.

Когда клиент входит в систему, служба управления идентификацией предоставляет клиенту JWT. Затем клиент может использовать этот токен для выполнения запросов к API. У API есть доступ к публичному ключу или секрету, который он использует для проверки токена.

Для проверки можно использовать, например, библиотеку jsonwebtoken. Приводим ниже код на JavaScript:

import jwt from 'jsonwebtoken'

export default function (req, res, next) {

// req.headers.authorization Bearer token

const token = extractToken(req)

jwt.verify(token, SECRET, { algorithms: ['HS256'] }, (err, decoded) => {

if (err) { next(err) }

req.session = decoded

next()

})

}

Больше информации про JWT, библиотеки и поддерживаемые языки программирования на сайте JWT.io.

4. Авторизация и привилегии доступа

Аутентификация важна, но так же важна и авторизация: имеет ли клиент, прошедший аутентификацию и получивший JWT, привилегию выполнить тот или иной запрос?

Чтобы проверить это, мы используем скоуп. Анализируя его, сервис API определяет, может ли этот запрос клиента быть выполнен без дорогостоящих операций поиска в списке контроля доступа.

Скоуп это текстовый блок (обычно разделённый пробелами), который описывает привилегии доступа конечной точки API. Там описаны Ресурсы и Действия, которые к ним можно применять. Такая формализация хорошо работает для REST / JSON API, поскольку они очень похожи по структуре.

RESOURCE: ACTION (например, ARTICLE: WRITE или ARTICLE: READ, где ARTICLE это ресурс, а READ и WRITE действия).

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

Спать спокойно

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

Документация

Что может быть хуже отсутствия документации? Устаревшая документация!

Разработчики относятся к документированию неоднозначно. У многих явно нет большой любви к этому делу. Как бы то ни было, эта задача очень важна особенно, когда речь идёт про публичное API. Сторонние разработчики должны иметь возможность изучить, как его использовать. Кроме того, хорошая документация поможет вам быстрее обучать новых разработчиков, пришедших в вашу команду.

Документация по API должна включать три базовых раздела:

1. Вводная часть (README)
2. Техническое описание (Спецификации)
3. Примеры использования (Getting started и другие подобные подразделы)

1. README

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

Об этом пишут в файле README. Этот файл обычно тоже размещают в репозитории, он даёт разработчикам отправную точку для работы с вашим проектом.

README должен содержать:

1. Описание API
2. Ссылки на технические справочники и руководства
3. Руководство по настройке для разработчика
4. Руководство для тестировщика
5. Руководство по развёртыванию
6. Управление зависимостями
7. Руководство для контрибьюторов
8. Нормы поведения
9. Лицензия
10. Благодарность

Будьте лаконичны в своем README; вам не нужно объяснять все нюансы, но предоставить достаточно информации, чтобы разработчики могли погрузиться в ваш проект.

2. Спецификации

В REST / JSON API каждая конечная точка представляет собой функцию, созданную с определённой целью. Важно иметь техническую документацию, описывающую каждую конечную точку, входные и выходные данные и особенности работы сервиса с разными клиентами.

Создать собственную документацию для API можно на основе OpenAPI.

Это спецификация и полноценный фреймворк для описания, создания, использования и визуализации веб-сервисовREST. Его задача позволить системам документации синхронизировать свои обновления с изменениями на сервере. Методы, параметры, модели и другие элементы посредством OpenAPI интегрируются с программным обеспечением сервера и всё время с ним синхронизируются.

3. Примеры использования

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

Отличный способ познакомить пользователей с вашим API создать подраздел Getting started (Начало работы). Это поможет разобраться с типовыми сценариями использования и на их примере оценить преимущества вашего API.

Три кита

Документация ключевой компонент любого API. Создавая документацию, помните о трёх китах успешного документирования API README, спецификации и примеры использования. И будет вам (и вашим пользователям) счастье!

Валидация данных

Многие часто упускают из виду такой важный аспект разработки API, как валидация данных. Валидация это процесс проверки входных данных, поступающих из внешних источников. Эти источники могут быть клиентом, отправляющим JSON, или службой, отвечающей на ваш запрос. Такая проверка позволит сделать так, чтобы данные были именно такими, какими они должны быть. Благодаря ей вы сможете устранить многие потенциальные проблемы. Важная задача валидации понять, какой формат и какую область значений должны иметь входные данные и как это контролировать.

Лучшая стратегия запускать проверку до того, как ваш сервис произведёт какие-то операции с данными. Когда клиент отправляет вашему API свои данные, например email, дату и имя, убедитесь, что это действительно адрес электронной почты, дата правильно отформатирована, а строка соответствует требованиям к длине. Эта простая проверка сделает работу вашего сервиса более безопасной и организованной.

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

Вы можете реализовать валидацию руками, но для этой цели также можно использовать и такие библиотеки, как Lodash или Ramda. Они отлично подходят для небольших объектов данных. Такие библиотеки, как Joi, Yup или Zod, работают ещё лучше, поскольку они позволяют описать общую схему валидации, сэкономив время и усилия. Если вам нужно что-то не зависящее от конкретного языка программирования, посмотрите на JSON Schema.

Лучше перебдеть

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

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

Тестирование

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

Интеграционное тестирование один из самых эффективных методов тестирования API. Его задача проверять, что приложение корректно переходит из одного состояния в другое. В нашем случае набор интеграционных тестов должен включать тестирование точек входа API сервиса, а также мокапы для имитации отправки запроса к нему и получения ответа. Таким образом мы проверяем основной тестовый сценарий нашего сервиса.

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

Для интеграционного тестирования я использую Tape, Test-server и Fetch-mock. Эти библиотеки позволяют запускать изолированные тесты для конечных точек API, проходя путь от запроса до ответа.

Игра в имитацию

Другие типы тестирования и проверки типов, безусловно, тоже полезны, интеграционное тестирование даёт наибольшее преимущество: оно показывает высокую эффективность при небольших тратах человеко-часов на написание и сопровождение тестов. А использование таких инструментов, как Fetch-mock, может обеспечить полную имитацию обмена данными.

Не останавливайтесь на достигнутом

Выполнив все четыре нефункциональных требования, не останавливайтесь на достигнутом. Есть ещё несколько: мониторинг приложения, логирование и управление API. Но в любом случае обеспечение безопасности, документирование, валидация и тестирование должны быть на первом месте.

---

Облачные серверы от Маклауд быстрые и безопасные.

Зарегистрируйтесь по ссылке выше или кликнув на баннер и получите 10% скидку на первый месяц аренды сервера любой конфигурации!