×

Огляд Karate — фреймворка для автоматизації тестування API

Усім привіт, мене звати Роман Любунь. Понад 15 років я займаюся автоматизацією, останні три з яких спеціалізуюся на впровадженні автоматизації тестування API на різних проектах. У цій статті розповім про молодий (~1,5 року) фреймворк — Karate, а також чому саме він був обраний для автоматизації інтеграційного тестування на моєму проекті.

Інформація буде корисною всім, кому потрібно:

  • легко розпочати API автоматизацію;
  • швидко збільшити тестове покриття (API automated tests) та нарощувати його синхронно з розробкою;
  • писати BDD тест-кейси/тести для автоматизації;
  • перевикористовувати тести для навантажувального тестування;
  • автоматизувати тести без досвіду програмування (але у будь-якому випадку вам потрібно вивчити основи REST API, XPath, regular expressions та знати Karate DSL синтаксис);
  • перевіряти JSON Schema.

Зараз я працюю на R&D проекті, де розробка ведеться з нуля, а замовник надає пріоритет якості над кількістю фіч (feature). Як результат, з’явилася можливість спробувати кожен з найбільш відомих API automation frameworks: REST Assured, Cucumber, Karate — та обрати найбільш оптимальний. Далі я розкажу коротко про проект та чому Karate підійшов найкраще. Також розглянемо можливості Karate-фреймворка, його переваги та недоліки.

Наш проект — це типове на сьогодні рішення: JavaScript + Angular — фронтенд, Java + Spring Boot — бекенд. Команда: три розробники та один тестувальник.

Підбір фреймворків

Власний фреймворк

Фреймворк представляє собою зв’язку: Rest HTTP client, Lombok, TestNG, AssertJ та Allure. Фреймворк успішно використовувався на багатьох попередніх проектах.

Спрощена архітектура власного фреймворка

Приклад тесту та основних методів:

/** Verify Vehicle's GET method. */
@Test
public void getVehicleTest() {
    Vehicle vehicle = createSimpleVehicle();
    Vehicle receivedVehicle = vehicleService.get(vehicle.getId());

    assertThat(receivedVehicle).as(“Created vehicle isn’t correct.”).isEqualToComparingFieldByField(vehicle);
}
 
/**
 * Service for Vehicle’s creation.
 * @return requested Vehicle object (with ID)
 */
private Vehicle createSimpleVehicle () {
        String UNIQUE_VEHICLE_NAME = “TestVechile” +  NumberUtils.getUniqueId();
        Vehicle vehicle = new Vehicle(UNIQUE_VEHICLE_NAME);
        int id = vehicleService.create(vehicle).getId();
        vehicle.setId(id);

        return vehicle;
}
 
/**
 * Vehicle's pojo
 */
@JsonInclude(JsonInclude.Include.NON_NULL)
@Data
@EqualsAndHashCode(exclude = "id")
public class Vehicle {
    private Integer id;
    @NonNull
    private String name;
    private String description;
}
 
/**
 * Vehicle's allowed methods
 * @param <T> - response type
 */
public interface VehicleService<T> {
    T create(T sendEntity);

    T get(int id);

    T update(T updatedEntity);

    void delete(int id);

    EntityPagination<T> getAll();
}
 
/**
* Create a Vehicle only with required parameters.
* @return - ID of created Vehicle.
*/
public int createSimpleVehicle() {
       Vehicle vehicle = buildSimpleVehicle();

       return vehicleService.create(vehicle).getId();
}

/**
* Build Vehicle object with filled required parameters. 
* @return - built Vehicle object
*/
public Vehicle buildSimpleVehicle() {
        return new Vehicle(SIMPLE_PREF + VEHICLE_NAME + NumberUtils.getUniqueId());
}
 
/**
 * Get entity
 * @param id - Entity's ID
 * @return - Entity's object
 */
public T get(int id) {
    return HTTP_CLIENT.sendRequest(getEndpoint() + id, HttpMethod.GET, null, getClassName()).getBody();
}

Фреймворк загалом відповідав початковим вимогам:

1. Швидкий старт та покриття функціоналу тестами паралельно з розробкою.

2. Можливість використання тестів (запуск та аналіз execution reports): замовником, розробниками та тестувальником.

Під час розвитку проекту замовник часто змінював основну бізнес-логіку (знайомо, правда? :)), що накладало особливі вимоги на швидкість оновлення тестів. Опис завдань (tasks) був доволі загальними, без деталей та критерій здачі (acceptance criteria). Тому з’явилися додаткові вимоги:

3. Потрібно документувати тест-кейси (раніше я писав лише тести), які використовуватимуться як частина специфікації. Після аналізу та затвердження замовником.

4. Можливість швидко оновлювати тести.

5. Звіт (raceability matrix) повинен відображати покриття функціоналу тестами та наявні дефекти.

Якщо коротко: більше документації та контролю за змінами. При виборі формату тест-кейсів (step — expected result чи given — when — then) замовник надав перевагу BDD.

Rest Assured

Після швидкого аналізу стало зрозуміло, що цей фреймворк економить час на старті (якщо у вас немає власного) і допомагає організувати тести в BDD стилі.

/** Simple Vehicle creation and verifying Vehicle's GET method. */
@Test
public void getVehicleTest() {
    Vehicle vehicle = createSimpleVehicle();
    int id = vehicle.getId();

    given()
    .when().get("/vehicle/" + id)
    .then()
           .body("name",equalTo(vehicle.getName()))
           .statusCode(200);
}

На жаль, навіть добре структуровані тести (в BDD форматі) не читабельні для замовника (особливо перевірки), тому доведеться писати тест-кейси.

Cucumber

BDD тест-кейси:

Feature: Vehicle API implementation

    Scenario: Create vehicle with only required fields filled
        Given Vehicle rest endpoint
        When Vehicle creates with unique name
        Then Return status code 200
            And Vehicle JSON with a new ID number
            And Vehicle JSON with given name

Наявні тести були поділені на кроки:

@When("^Vehicle creates with unique name$")
public int vehicleCreatesWithUniqueName() throws Throwable {
      String UNIQUE_VEHICLE_NAME = “TestVechile” +  NumberUtils.getUniqueId();
        Vehicle vehicle = new Vehicle(UNIQUE_VEHICLE_NAME);
        return vehicleService.create(vehicle);
}

Це допомогло виконати вимоги № 3 (Gherkin скрипти замінили тест-кейси) та № 5 (traceability matrix), але ще більше ускладнило № 4 (підтримка актуальності тестів), оскільки до наявного фреймворка додались ще два логічні рівні (кроки та Gherkin скрипти). Як наслідок, суттєво зросли часові затрати на підтримку коду. Після цього я вирішив спробувати найменш відомий із фреймворків.

Karate

Приклад тесту:

Scenario: Create vehicle with only required fields filled
  Given url baseUrl + 'vehicle'
  * def name = 'TestVehicle' + Java.type("utils.NumberUtils").getUniqueId();
  And request { name: '#(name)' }
  When method POST
  Then status 200
  And match response = { id: '#number', name: '#(name)' }

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

Дивіться також більш детальне порівняння Karate з REST Assured та Cucumber.

Karate DSL

Karate написаний на Java поверх Cucumber-JVM (доступні всі можливості та звітування).

Розробник: Peter Thomas
GitHub-рейтинг: ~1.3k stars
Поточна версія: 0.8.0.1
Ліцензія: MIT

Основні можливості:

  • DDT testing;
  • ‘natively’ support JSON, XML;
  • JsonPath, XPath expressions;
  • Schema validation;
  • Can call JS functions, Java methods;
  • Tags for tests grouping;
  • Parallel execution;
  • Java API (e.g. call *.feature from Selenium tests);
  • Tests can be reused for Gatling performance tool;
  • Complex HTTP calls: SOAP/XML requests, HTTPS/SSL (without needing certificates, key-stores or trust-stores), HTTP proxy server support, URL-encoded HTML-form data, multi-part file-upload, browser-like cookie handling, full control over HTTP headers, path and query parameters;
  • GraphQL API testing;
  • IDE support (with autocomplete);
  • Support TestNG/JUnit;
  • Built-in environment switcher;
  • Tool for step-by-step debugging;
  • Integration with CI/CD pipelines;
  • Build-in test report (feature > scenario traceability matrix);
  • API mock server for test-doubles;
  • Mock HTTP servlet for testing any controller servlet such as Spring Boot / MVC or Jersey / JAX-RS — without having to boot an app-server.

Приклад роботи автозаповнення

Повний список можливостей та документація.

Приклади Karate тестів

Простий тест для перевірки CRUD (тестування базових методів: POST, GET, PUT, DELETE + групування тестів):

@smoke  # Можна додавати власні теги для групування тестів.
Scenario: Delete Vehicle by ID
  * url baseUrl + 'vehicle'
  Given path id
  When method DELETE
  Then status 200
  When path id
  And method GET
  Then status 404

DDT тест:

@smoke  # Приклад використання декількох тегів
@positive
Scenario Outline: Create an Vehicle with a valid parameters
  # Можна викликати Java метод(и) з тесту.
  * def uniqueNumber = Java.type("utils.NumberUtils").getUniqueId();
  * def name = 'TestVehicle' + uniqueNumber
  * def description = 'Description' + uniqueNumber
  # Запит можна описувати зразу в JSON форматі. Пропадає необхідність використовувати pojo.
  Given request { name: <name>, description: <description> }
  When method POST
  Then status 200
  # Значення name, description братимуться з таблиці нижче.
  And match response == { id: '#number', name: <name>, description: <description> }
  # Тест виконуватиметься стільки разів скільки є рядків у таблиці.
  Examples:   
    |  name                         | description                          |
    |  '#(name)'                    | '#(description)'                     |
    |  'TestName'                   | '#(description)'                     |
    |  'TestName'                   | '#(description)'                     |
    |  ''                           | '#(description)'                     |
    | 'Test_Longest_Possible_Name'  | '#(description)'                     |
    | '#(name)'                     | null                                 |
    | '#(name)'                     | ''                                   |
    | '#(name)'                     | 'Test_Longest_Possible_Description'  |

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

Недолік: кількість рядків в таблиці фіксована. Це обмеження прийшло з Cucumber фреймворка, на якому базується Karate.

Приклад виклику іншого тесту з pre-conditions:

Feature: Operator API
  # Повторювані передумови можна винести в Background секцію яка виконується на початку кожного тесту в межах *.feature-файлу.
  Background:
    * url baseUrl + 'operator'
    # Створення тестових даних, також, можна винести в окремий файл маючи зручний доступ до його результатів та змінних.
    * def operator = call read('classpath:api/operator/create-smpl-operator.feature')
    * def id = get operator.response.id

  Scenario: Get an Operator by ID
    Given path id
    When method GET
    Then status 200
    # Довгий JSON можна відформатувати для кращої наглядності.
    And match response == 
                          """
                             {
                               description: null,
                               id: '#number',
                               name: '#(operator.operatorJson.name)'
                             }
                          """

Недолік: при перейменуванні чи зміні логіки (порядку виклику) *.feature-файлів IDE не відслідковує залежності. Тому потрібно бути дуже уважним, щоб не «поламати» зв’язки між тестами.

Приклад перевірки JSON-схеми:

Scenario: Validate country's schema
  Given url baseUrl + 'country'
  # Частину вкладеного (nested) JSON можна винести окремо.
  * def oddSchema = {price:'#string', status:'#? _ < 3', ck:'##number', name:'#regex[0-9X]'}
  # Для перевірки складних значень можна викликати сторонні JS функції чи Java методи.
  * def isValidTime = read('time-validator.js')
  When method get
  Then match response ==
         """
            {
             id: '#regex[0-9]+',                 # Підтримка regexp
             count: '#number',                   # Значення має бути числом
             odd: '#(oddSchema)',
             data: {
                    countryId: '#number',
                    countryName: '#string',     # Значення має бути стрічкою
                    leagueName: '##string',     # Значення може бути відсутнім або є стрічкою
                    status: '#number? _ >= 0',
                    sportName: '#string',
                    time: '#? isValidTime(_)'
                   },
             odds: '#[] oddSchema'               # Значення має бути масивом
            }
         """

Підтримка JsonPath, XPath expressions та RegExp дає широкі можливості написання складних перевірок.

Недолік: доводиться замовнику пояснювати, що означають ті чи інші перевірки.

Приклад авторизації за допомогою Token:

# Тег для позначення *.feature файлів які не є тестами (не потрібно виконувати).
@ignore
Feature: oauth2


  # Функціонал для автентифікації та отримання token
  Scenario: oauth2 authentication
    * url 'https://myserver.com:8443/auth/realms/myproject/protocol/openid-connect/token'
    * form field grant_type = 'password'
    * form field client_id = 'myproject_login_local'
    * form field client_secret = 'f30ca900-ed60-4h7d-8aac-349e432c7b9a'
    * form field username = 'administrator'
    * form field password = 'adminPwd'
    * method post
    * status 200
    * def accessToken = response.access_token
    * def authorization = { Authorization: '#("Bearer " + accessToken)' }

Приклад тесту з автентифікацією:

@smoke
Feature: Fleet API


  Scenario: Get Fleet by ID
    # Додавання token (який був згенерований в oauth2.feature) до headers.
    * configure headers = headers.authorization
    * url baseUrl + 'fleet'
    * def fleet = call read('classpath:api/fleet/create-smpl-fleet.feature')
    * def id = get fleet.response.id
    Given path id
    When method GET
    Then status 200

Для перемикання між різними середовищами (environment) використовується karate-config.js (викликається перед кожним тестом):

function() { 
  var env = karate.env; // вибір середовища при запуску з командної стрічки. 


  // середовище за замовчуванням (при виконанні з IDE)
  if (!env) {
    env = 'dev';
  }
  
  var config = {
    env: env,
    // Так можна отримати ім’я сервера наприклад з Java методу.
    // baseUrl – змінна яка використовується як root url у всіх тестах.
    baseUrl: Java.type('utils.PropertyValues').getServerUrl() + ':8086/v1/api/config/'
  }
  // Так ми автентифікуємось та отримуєм token перед виконанням тестів.
  config.headers = karate.callSingle('classpath:api/authentication/oauth2.feature', config);


  if (env == 'dev') {
  // в заледжності від обраного оточення можна змінювати глобальні змінні, наприклад: config.foo = 'bar';
  } else if (env == 'e2e') {
    // змінні для іншого оточення
  }
 
  // визначення максимальної тривалості запиту та інші параметри фреймворку.
  karate.configure('connectTimeout', 5000);
  karate.configure('readTimeout', 10000);
  return config;
}

Недолік: тим, хто звик писати тести на Java, потрібно вивчити основи JavaScript.

Паралельне виконання тестів та генерація звіту:

@CucumberOptions(tags = {"~@ignore"})
public class APIParallelExecutorTest {
        @Test
        public void executeInParallel() {
            String karateOutputPath = "target/surefire-reports";
            KarateStats stats = CucumberRunner.parallel(getClass(), 100, karateOutputPath);
            generateReport(karateOutputPath);
            assertTrue("scenarios failed", stats.getFailCount() == 0);
        }


    # Я додатково використовую cucumber-reporter для кращої наглядності.
    private static void generateReport(String karateOutputPath) {
        Collection<File> jsonFiles = FileUtils.listFiles(new File(karateOutputPath), new String[] {"json"}, true);
        List<String> jsonPaths = new ArrayList(jsonFiles.size());
        jsonFiles.forEach(file -> jsonPaths.add(file.getAbsolutePath()));
        Configuration config = new Configuration(new File("target"), "My_project");
        ReportBuilder reportBuilder = new ReportBuilder(jsonPaths, config);
        reportBuilder.generateReports();
    }
}

Приклад інтеграції UI та API тестів:

// Перевірка створення Fleet через UI.
@Test
public void createFleet() {
    //Перехід на сторінку для створення Fleet.
    applicationPage.navigate(BASE_URL);

    //Створення Fleet через UI.
    String fleetName = "TestFleetName" + UNIQUE_ID;
    ConfigurationPage configurationPage = applicationPage.openConfiguration();
    configurationPage.addFleet(fleetName);

    //Перевірка чи Fleet створений (через API).
    List<Map<String, Object>> allFleets = fleetApiSteps.getAllFleets();
    int numOfFleetsWithName = filterEntitiesByName(allFleets, fleetName).size();
    Assert.assertTrue(String.format(MSG_MORE_THEN_ONE_FOUND_VIA_API, numOfFleetsWithName, fleetName),
            numOfFleetsWithName == 1);
    //Перевірка чи Fleet з’явився на сторінці (UI).
    Assert.assertTrue(String.format(MSG_NOT_VISIBLE_ON_UI, fleetName),
            configurationPage.isFleetDisplayed(fleetName));
}
 
// Виклик *.feature (API) файлу та опрацювання результату на Java.
public List<Map<String, Object>> getAllFleets() {
    Map<String, Object> result = CucumberRunner.runClasspathFeature("api/fleet/get—all-fleets.feature", null, true);
    Map<String, Object> response = (Map<String, Object>) result.get("response");
    return (List<Map<String, Object>>) response.get("content");
}

Відео демо створення та виконання API тестів.

Звітування

Після виконання тестів генерується такий список звітів (після підключення Cucumber reporter):

  • загальний по всіх *.feature-файлах;
  • тільки список помилок;
  • по тегах;
  • індивідуальні звіти для кожного *.feature-файлу.

Звіт по фічах

Звіт по тегах

Звіт тесту з помилкою

Висновки

На основі розроблених тестів можна зробити такі висновки: основна перевага Karate в простоті та наочності тестів, великій кількості можливостей «з коробки» та гнучких перевірках.

Karate добре підходить для:

  • швидкого старту API автоматизації; особливо, якщо QA інженери мають мінімальний досвід програмування;
  • проектів з тест-кейсами в BDD форматі;
  • проектів, на яких ці ж сценарії використовуються для навантажувального тестування.

Менше підходить:

  • якщо потрібно тісно інтегрувати UI та API автоматизацію;
  • якщо API фреймворк додатково потребує складних функціональних рішень на Java/JavaScript.

Основні недоліки:

  • підтримуються лише JS, Java як допоміжні мови;
  • наразі сфера використання обмежується лише API;
  • умови (if..else) можна реалізувати лише через JavaScript/Java;
  • для збереження «читабельності» тестів потрібно дублювати код.

Усім дякую. Сподіваюсь, ця стаття допоможе вам у виборі оптимального API фреймворка. Якщо у вас виникнуть питання, зауваження чи уточнення, буду радий відповісти.

Все про українське ІТ в телеграмі — підписуйтеся на канал DOU

👍ПодобаєтьсяСподобалось4
До обраногоВ обраному2
LinkedIn

Схожі статті




13 коментарів

Підписатись на коментаріВідписатись від коментарів Коментарі можуть залишати тільки користувачі з підтвердженими акаунтами.

Мда... BDD и Rest API тестирование как отдельный вид извращений. Ну ладно есть MSpec там это проще и более акуратно реализовано. Больше порадовало то что занимает 5 строк на пайтоне тут размазано на 3 скрола экрана.

Больше порадовало то что занимает 5 строк на пайтоне тут размазано на 3 скрола экрана

Що саме?

erikbern.com/assets/dsls.png

Завжди мене бісили всі ці DSL. Ну, напишете ви все це на Karate DSL. А звільниться людина — як будете шукати нову? Багато відгукнеться бажаючих на вакансію з описом «Karate DSL required» ? Більше того — а як тій самій людині, що це писала, знайти нову роботу з такою унікальною вузькою спеціалізацією? Виходить жорсткий лок фірми на людині і людини на фірмі. То до добра не доведе, бо незамінних не повинно бути.

Чому б не писати тести API на якійсь звичайній, розповсюдженій мові програмування?

Кандидатів, як правило, ніколи не шукають зі 100% попаданням в вакансію, бо все рівно є і свій домент знань і свої історичні особливості проекту, тощо. Тобто доучувати треба завжди! І вивчити цей DSL це пару днів максимум.

завжди!

Хотел поставить like, но потом заметил это бесячий бессысленый «!»

Одвічна проблема нових мов, підходів, фреймворків. Іноді «вирішення» проблеми (швидше, меншими ресурсами) стоїть набагато гостріше.

# Можна викликати Java метод(и) з тесту.

цікава фіча, але більше підтримую винести такі речі в окремий Given крок або реалізовувати в першому кроці

дана фіча корисна для: інтеграції з UI tests, утилітних методів (як в прикладі). Де розмістити виклик питання звички.

BDD тест-кейси:

ідея BDD — описувати вимоги у вигляді сценаріїв поведінки. Ці ж сценарії можуть використовуватись і для тестування. Термін тест кейс тут недоречний.

умови (if..else) можна реалізувати лише через JavaScript/Java;

а як би ви хотіли їх реалізовувати ?
Через кукмбер сценарій ? тоді тест не буде детермінований

для збереження «читабельності» тестів потрібно дублювати код.

можна про це детальніше ?

а як би ви хотіли їх реалізовувати ?

Ідея полягала у пере використанні сценарію в залежності від умов.

можна про це детальніше ?

1. Для перевірки response можна брати request (додаючи/модифікуючи потрібні поля), але таке рішення нечитабильне. Іноді краще вставляти повністю JSON.
2. Багато що можна повиносити в інші *.feature файли, але це погіршує читабельність тестів.

Ідея полягала у пере використанні сценарію в залежності від умов.

на різні умови повинні бути різні сценарії. Тобто, якщо тестуєте логін, то є один сценарій на успішний логін і окремі сценарії на не успішний логін.

З логіном все вірно. Виникають ситуації коли наявність логічного оператора допомагає писати суттєво компактніший код, як наприклад цикл (scenario outline) для TDD.

такі речі повинні бути реалізовані у самому кроці

Підписатись на коментарі