Всем привет! Меня зовут Катя Муличева, я тестировщица в СИБУР Диджитал. Последние два года я пишу автотесты для gRPC на Kotlin. Получив опыт, я захотела написать статью, которая очень пригодилась бы мне самой, когда я только начинала разбираться с gRPC. Надеюсь, вы найдете её полезной для себя!
Немного теории
Для чего нужен API
Начнём с основ. У нас есть сервисы, которые могут быть написаны на разных языках и использовать разные протоколы. Чтобы они могли между собой общаться, нам нужно организовать способ передачи сообщений. Один из таких способов — RPC и его модификация от Google — gRPC.
gRPC использует для общения формат protobuf, также придуманный Google. Хотя можно использовать и другие форматы — говорят, не протобафом единым живет gRPC. Но здесь я буду писать только про protobuf.
Когда может пригодиться gRPC
Если в проекте используются микросервисы, которые общаются друг с другом;
Если в проекте много разных частей написаны на разных языках программирования — у gRPC есть кодогенерация для многих популярных языков;
Если данные надо стримить — gRPC умеет с этим работать, потому что использует протокол HTTP/2, в котором легко работать с потоками;
Если важна скорость передачи — gRPC работает быстрее, потому что использует данные для передачи в бинарном виде. И ещё из-за других новшеств HTTP/2, но в них не будем углубляться.
Так как именно работает GRPC?
Делаем прото-запрос и получаем прото-ответ. Похоже на привычный рест? Да, только есть особенность: передаваемые и получаемые данные сохраняются в бинарном виде, а ключи для данных — это индексы, а не привычные в ресте имена полей. Так что данные передаются быстро, но выглядят непонятно для человека, будучи зашифрованными в бинарном виде.
Поскольку этот текст написан для тестировщиков, мы будем рассматривать как работать с клиентом gRPC, а сервер писать не будем.
Чтобы работать с gRPC понадобится :
Прото-файл (который выступит для нас документацией какие прото-запросы и прото-ответы мы можем получать);
Стаб — это клиент для сервиса, описанного в прото-файле. Мы создадим его, используя кодогенерацию gRPC, или стабом выступит само приложение, через которое мы делаем запрос;
Адрес API, куда будем слать запросы.
Что можно использовать для тестирования gRPC?
Традиционно предлагают использовать BloomRpc для Windows. Все просто: добавляешь прото-файл, вводишь адрес API. В нужном запросе дополняешь поля данными и запускаешь. Клиент — само приложение BloomRpc.
Для MACos есть другой инструмент, такой же простой: grpc_clicker. Вот ссылка на гитхаб и на маркетплейс VSCode.
Ещё есть мультиплатформенный Postman, в котором теперь тоже поддерживается возможность использовать gRPC.
Если вы подгрузили файл и выполняете запрос, но все равно ничего не работает — возможно, дело в том, что у вас перед выполнением запроса требуется авторизация еще каким-нибудь API. Самый простой вариант решения: отключите авторизацию и попробуйте еще раз. Ввод пароля и логина, получение токена перед выполнением запроса можно попробовать настроить в Postman, но это трудоёмкий процесс.
И к практике
Переходим к созданию автотестов. С нуля и пошагово!
Мы будем писать автотесты по прото-файлу Dogs вот отсюда, на языке Kotlin. А для сборки будем использовать Spring Boot и Gradle.
Предварительная настройка
Открываем InteliIjIDE. Выбираем Console Application и 11 версию Java. В качестве сборщика будем использовать Gradle.
Ура, заготовка есть. Теперь ждем некоторое время, пока проект собирается (внизу справа Gradle Build с полосой загрузки):
После того как все собралось — делаем Package.
И перетаскиваем в него Main.kt. Это нужно для корректного запуска.
Теперь поменяем код в нашем файле main. Оригинал выглядит примерно так:
А меняем мы его вот на это:
package t
import org.springframework.beans.factory.annotation.Value
import org.springframework.boot.CommandLineRunner
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
@SpringBootApplication
class DogsTestApp() : CommandLineRunner {
companion object {
@JvmStatic
fun main(args: Array<String>) {
runApplication<DogsTestApp>(*args)
}
}
override fun run(vararg args: String?) {
}
}Мы будем запускать приложение, используя SpringBoot. Дальше мы дополним этот файл, но пока оставим такую заготовку.
На этом этапе сделаем папку proto, где будем хранить наши прото-файлы.
Помещаем туда наш прото-файл:
И вот так он выглядит:
Теперь идём в файл build.gradle.kts:
Сейчас в нем автоматически сгенерированный код, который мы заменим кодом ниже. В этом файле мы прописываем, какие именно версии библиотек нам нужны. Обратите внимание, что здесь надо указать название Package, который мы создали в начале, в этой строке “group= "t"”.
И еще здесь мы указываем класс, который будет использоваться для запуска приложения
springBoot{ mainClass.set("t.DogsTestApp")
Код, который заменит автоматический:
import com.google.protobuf.gradle.id
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
plugins{
id("org.springframework.boot")version"2.7.0"
id("io.spring.dependency-management")version"1.1.0"
id("com.google.protobuf")version"0.9.2"
kotlin("jvm")version"1.7.22"
kotlin("plugin.spring")version"1.7.22"
}
group= "t"
version= "0.0.1-SNAPSHOT"
java.sourceCompatibility= JavaVersion.VERSION_11
ext["grpcKotlin"] = "1.3.0"
ext["grpcVersion"] = "1.53.0"
ext["protobufVersion"] = "3.22.0"
repositories{
mavenCentral()
}
springBoot{
mainClass.set("t.DogsTestApp")
}
protobuf{
protoc{
artifact = "com.google.protobuf:protoc:${rootProject.ext["protobufVersion"]}"
}
plugins{
id("grpc"){
artifact = "io.grpc:protoc-gen-grpc-java:${rootProject.ext["grpcVersion"]}"
}
id("grpckt"){
artifact = "io.grpc:protoc-gen-grpc-kotlin:${rootProject.ext["grpcKotlin"]}:jdk8@jar"
}
}
generateProtoTasks{
all().forEach{
it.plugins{
id("grpc")
id("grpckt")
}
it.builtins{
id("kotlin")
}
}
}
}
dependencies{
implementation("org.springframework.boot:spring-boot-starter")
implementation("net.devh:grpc-client-spring-boot-starter:2.14.0.RELEASE")
implementation("org.jetbrains.kotlin:kotlin-reflect")
implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
implementation("io.grpc:grpc-kotlin-stub:${rootProject.ext["grpcKotlin"]}")
implementation("io.grpc:grpc-protobuf:${rootProject.ext["grpcVersion"]}")
implementation("com.google.protobuf:protobuf-kotlin:${rootProject.ext["protobufVersion"]}")
implementation("com.google.protobuf:protobuf-java:${rootProject.ext["protobufVersion"]}")
runtimeOnly("io.grpc:grpc-netty-shaded:${rootProject.ext["grpcVersion"]}")
compileOnly("org.apache.tomcat:annotations-api:6.0.53")
testImplementation("org.springframework.boot:spring-boot-starter-test")
}
tasks.withType<KotlinCompile>{
kotlinOptions.jvmTarget = "1.8"
}
tasks.withType<Test>{
useJUnitPlatform()
}
Если вы сделали всё описанное выше, то на этом этапе у вас должны появиться вот такие значки. Они показывают, что надо подгрузить файлы и собрать проект заново.
Нажимаем сперва на один значок файла, затем на другой (на слона). Мы изменили файл настроек, и теперь эти изменения должны вступить в силу с загрузкой нужных нам библиотек.
После того как все подгрузится, красный текст (на скрине) пропадет.
Далее идем в settings.gradle.kts.
Здесь мы пишем, что создали папку с прото-файлами и её тоже будем использовать как часть проекта. Затем опять пересобираем проект, нажав на уже знакомый значок слона.
Создаём клиента
Создаём new package service, а в нём — new Kotlin class под названием DogsClientService. В учебных целях будем рассматривать симулятор собаки. Да.
Также не забудем на этом шаге сбилдить прото-файлы, чтобы нам удобнее было писать автотест, используя их. Для этого нужно сперва открыть Gradle сбоку и сделать двойной клик на clean. А затем сделать двойной клик на build.
Теперь возвращаемся к DogsClientService, делаем импорты и нотации
И начинаем описывать наш стаб. Поскольку мы сбилдили с помощью Gradle наши прото- файлы (это можно увидеть, если открыть сбоку extracted-protos ), мы увидим появление нашего DoggRPC.
И значит теперь, благодаря кодогенерации, у нас будут появляться подсказки!
Выбираем BlockingStub, потому что у нас обычный запрос, не потоковый и не асинхронный. Ниже мы описали, что этот клиент будет работать с запросом для гавканья:
А запрос и ответ известны нам из прото-файла.
Фактически, мы написали, что наш клиент будет работать с этим запросом.
Теперь сделаем класс DogSteps, в котором напишем метод, отправляющий наш запрос для гавканья makeBark.
Сейчас у нас очень простой вызов метода API с запросом без параметров, поэтому строчки 11 и 13 кажутся избыточными, но в дальнейших примерах мы увидим, что здесь можем добавлять данные в наш request .
А пока делаем его таким и на 14 строке пишем вызов метода API barkRequest, который написали в клиенте DogsClientService (обратите внимание, что в 7 строке мы создали экземпляр этого клиента) с нашим запросом request2. И кладем его в переменную getResponse — данные, которые нам придут после выполнения запроса.
Идем в Main.kt и делаем импорт командойimport t.DogSteps.
Затем дописываем в DogsTestApp переменную внутри скобок (private val mydogSteps:DogSteps) и переписываем метод run, в котором мы через созданную переменную mydogStep запускаем вызов метода MakeBark.
Остаётся заключить наш вызов метода в try catch, чтобы можно было увидеть ошибки, если запрос не сможет выполниться.
И последний шаг — в resources создаем файл application.properties, в котором пишем адрес, где находится API, к которому мы будем обращаться.
И теперь мы можем запускать наш API-тест, нажав на зеленую стрелку!
Правда сейчас он у нас не выполнится, потому что адрес static://your_name:1234 не содержит в себе ручку нашего API. Чтобы увидеть запуск придется поднимать у себя локально API с нашим прото-файлом или, используя этот пример как основу, написать запрос к своему API, который вы тестируете.
Полезные советы.
3.1. Для сложных мессаджей в прото-файле.
Возьмём исходный message BarkRequest {}и допишем в него уточняющие параметры — кто гавкает, где, почему и сколько раз (и не забудьте пересобрать через Gradle clean и затем build).
message BarkRequest {
string whoBark = 1;
string whereBark = 2;
string whyBark = 3;
int howManyTimesBark = 4;
}
Идём в DogSteps, и теперь наш запрос будет не такой простой, как раньше — мы увидим предложенные варианты методов заполнения созданных полей.
Допишем в параметры метода, что будем ожидать эти данные для заполнения полей и в request1. А дальше все как прежде.
И соответственно указываем данные при вызове:
3.2. Assertion.
Без Assertion автотесты не обходятся, и в нашей конфигурации мы можем использовать, например, такую библиотеку:
import org.hamcrest.MatcherAssert
import org.hamcrest.core.IsИ пример её использования:
val sendingPeriod = myConstantForCheck
val a = somePage.sendingPeriod.text
var b = a.replaceAfter(" ", "")
println(b.toString())
println("ffffff")
MatcherAssert.assertThat(
"is equal",
b,
Is.`is`(sendingPeriod + " ")
)
3.3. log info
Вывод данных в консоль тоже очень полезен. Подключаем:
import org.slf4j.LoggerFactory
private val log = LoggerFactory.getLogger(*javaClass*)И пара примеров использования:
# Первый
log.info(request2.*whoBark*.toString())
# Второй
log.info(getResponse.*message*.toString())3.4. А если наше сообщение использует другое сообщение?
Допустим, наш прото-файл бы выглядел еще сложнее. С новым мессаджем PlayRequest.
Если наш запрос состоит не просто из значения, а из вложенных мессаджей, мы можем использовать паттерн фабрики для заполнения запроса. Для этого сделаем следующий класс.
А в DogsClientService допишем метод для нового запроса playRequest.
И теперь в DogSteps вот так заполним наш запрос, используя созданный класс toyFactory.
Эпилог
На сегодня всё! Спасибо, что прошли этот подробный гайд вместе с нами, и дайте знать, если хотите больше подобных материалов :)