Karate

Karate is an API testing framework that uses readable feature files to define requests, assertions, data setup, and scenario flow. It is especially useful when QA engineers and developers need to review API behavior without translating everything into a general-purpose test language.

This tutorial explains the core Karate workflow and then shows where it can fit with documented webmate API usage, such as authenticating with an API key and exercising supported REST endpoints.

Goal

By the end of this tutorial you will understand how to create a Karate project, write a feature file, configure environments, assert response structure, run data-driven scenarios, produce reports, and execute the suite in CI.

Before You Start

You need a Java runtime and a build tool or the Karate CLI. You also need an API endpoint you are allowed to test. If you test webmate APIs, use the documented API pages and keep API keys in environment variables or CI secrets.

Karate tests are written in .feature files. The syntax is inspired by Gherkin, but Karate steps are executable API operations rather than only human-readable specifications.

Project Setup

A simple project can keep features under src/test/resources/features:

1
2
3
4
5

src/test/resources/
  karate-config.js
  features/
    health.feature
    projects.feature

karate-config.js returns values shared by the suite:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

function fn() {
  var env = karate.env || 'dev';
  var config = {
    baseUrl: 'https://api.example.com',
    apiKey: java.lang.System.getenv('API_KEY')
  };

  if (env === 'staging') {
    config.baseUrl = 'https://staging-api.example.com';
  }

  karate.configure('headers', {
    Accept: 'application/json'
  });

  return config;
}

Keep secrets outside the file. Configuration should describe environments, not contain credentials.

Step 1: Write a First Feature

A feature file describes one API area and one or more scenarios.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Feature: Health endpoint

  Background:
    * url baseUrl

  Scenario: service reports healthy status
    Given path 'health'
    When method get
    Then status 200
    And match response.status == 'ok'

The Background runs before each scenario. Use it for shared URL, headers, or setup that every scenario in the file needs.

Step 2: Send Authenticated Requests

Most real API tests need headers. Put shared authentication in Background or karate-config.js.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Feature: Project API

  Background:
    * url baseUrl
    * header Authorization = 'Bearer ' + apiKey

  Scenario: list projects
    Given path 'projects'
    When method get
    Then status 200
    And match response == '#[]'

Use broad assertions for lists when item order or exact shape is not the purpose of the test. Use strict assertions when the contract requires exact fields.

Step 3: Assert Response Shape

Karate’s match syntax is compact and expressive.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Then status 200
And match response ==
  """
  {
    id: '#string',
    name: '#string',
    createdAt: '#string',
    active: '#boolean'
  }
  """

Use type markers for generated values. Exact equality is useful for deterministic fields, but brittle for timestamps, IDs, and server-generated metadata.

Step 4: Use Data-Driven Scenarios

Scenario outlines let one test run with multiple examples.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Scenario Outline: invalid login is rejected
  Given path 'login'
  And request { email: '<email>', password: '<password>' }
  When method post
  Then status 401

  Examples:
    | email              | password |
    | missing@example.io | bad      |
    | tester@example.io  | wrong    |

Use data-driven tests for boundary values and repeated contract checks. Avoid turning one scenario outline into an entire test plan; large tables are hard to diagnose.

Step 5: Run Tests and Reports

Run all features:

1

karate run src/test/resources/features

Run by tag and environment:

1

karate run -e staging -t @smoke src/test/resources/features

Karate produces HTML reports by default and can produce JUnit XML or Cucumber JSON for CI systems.

1

karate run -f cucumber:json,junit:xml src/test/resources/features

Keep reports as CI artifacts. API failures are much easier to review when the request, response, status, and assertion are visible.

Step 6: Run in CI

A CI job should install dependencies, inject secrets, choose an environment, and run a tagged subset or full suite.

1
2

export API_KEY="$WEBMATE_APIKEY"
karate run -e staging -t @smoke src/test/resources/features

Use tags to separate smoke tests, destructive tests, and slow end-to-end scenarios. Never run destructive API tests against production unless the API and data are explicitly designed for that.

How This Maps to webmate

webmate exposes documented API and SDK workflows for project and test management tasks. Karate can test those documented endpoints from the outside, just like any other HTTP API, as long as the request shape comes from the public documentation.

For example, a Karate suite can validate that an API key is accepted, that a documented resource can be listed, or that a test-run workflow returns the expected status. Keep the tests aligned with the REST API and Generate API Key documentation. Do not encode private endpoints or assumptions discovered from browser traffic.

Debugging

If a scenario fails before the request, check baseUrl, environment selection, and variables. If it fails with 401 or 403, check API key scope and header formatting. If the status is correct but match fails, inspect whether the API contract changed or the assertion is too strict for generated data.

Mask secrets in logs when running in shared CI. Karate supports log masking options in CLI usage; use them for passwords, tokens, API keys, and personal data.

Verify the Result

A good Karate setup can run locally, select environments, filter by tags, produce reports, and fail clearly when a response violates the contract. For webmate API usage, the test should only cover documented endpoints and keep credentials outside the repository.

Next Steps

Use the API and SDKs section for documented webmate API workflows. Use Robot Framework if the team prefers keyword-driven suites that coordinate API, browser, mobile, and system checks under one syntax.