Technical Deep Dive: File Structure and Best Practices in Karate DSL

In the world of API test automation, Karate DSL stands out for its simplicity, power, and ability to handle both HTTP requests and validations in a readable format. At the heart of every Karate test lies the feature file — a neatly structured script that combines Gherkin syntax with Karate’s DSL capabilities.

Whether you’re a beginner writing your first test or an experienced tester looking to optimize your scripts, understanding the structure of a Karate feature file is key to writing clean, maintainable, and scalable tests.

In this post, we’ll walk through the core building blocks of a Karate test script, explore best practices, and share tips to help you avoid common pitfalls.

The Karate framework adopts Cucumber-style Gherkin syntax to support a BDD approach, organizing tests into three core sections: Feature, Background, and Scenario.

Let’s understand the structure of the KARATE Framework

Step 1: Create a new MAVEN Project

• Choose a Workspace location.
• Select the Archetype
• Provide the Group ID and the Artifact ID
• Click on Finish to complete the setup.

Step 2: The following will be the structure

A Karate test script typically includes:

1. Feature: to describe a test suite
2. Background: for shared setup (optional)
3. Scenario(s): with Given‑When‑Then steps
4. DSL steps like def, request, match
5. Use of Scenario Outline + Examples or JS loops for data tests
6. Runner in Java (JUnit 4/5) to execute feature files

A Karate test script uses the .feature extension, a convention inherited from Cucumber. You can organize your files according to the Java package structure if you prefer.

While Maven guidelines suggest keeping non-Java files separately in the src/test/resources directory and Java files in src/main/java, the creators of the Karate Framework recommend a different approach. They advocate for storing both Java and .feature files together, as it makes it easier to locate related files, rather than following the typical Maven file structure.

1. Feature File (*.feature)

These are your .feature files where you write Karate tests using Gherkin syntax. They serve as the entry point for your API testing, allowing you to describe test behavior in plain English. Feature files contain:

• Feature: – a high-level description of what’s being tested.

• Background: (optional) – shared setup that runs before each scenario (e.g., setting base URL, headers).

• Multiple Scenarios (or Scenario Outline) with steps to test specific API endpoints.

Karate uses Gherkin-style .feature files. These include:

a. Feature:

A high-level description that groups related scenarios.

Feature: User API tests

         Validate creation, retrieval, and deletion of users

b. Background: (optional)

Steps common to all scenarios in the file, like setting the base URL or the auth token.

Background:

       Given url baseUrl
       And header Authorization = 'Bearer xyz'

c. Scenario: / Scenario Outline:

Each Scenario: describes a test case.

Scenario Outline: allows data-driven tests combined with an Examples: table.

Scenario: Create a new user 
          When method post 
          And request { name: 'Alice', email: 'alice@example.com' } 
          Then status 201 
          And match response.id != null


Scenario Outline: Test multiple user creation 
  Given request { name: <name>, age: <age> }
  When method post
  Then status 201
  Examples:
    | name  | age |
    | Alice | 25  |
    | Bob   | 30  |

2. Gherkin Steps with Karate DSL

Karate supports the standard Given‑When‑Then keywords, but the logic is built into its DSL (no Java step definitions needed). Karate DSL is a powerful, open-source, domain-specific language designed to streamline API testing. Unlike frameworks that require extensive coding, Karate employs a human-readable syntax—built on Gherkin-style keywords like Given, When, Then— so you can express tests in plain English.

Common step types:

• Given – setup (e.g., url, header, param)
• When – action (e.g., method get/post)
• Then / And – assertions (e.g., status, match)
• * def – define variables or functions
• * call read(...) – reuse other feature files
• * print, * eval, JSON manipulation

Example:

Scenario: Search for user 
      * def searchQuery = {term: 'example'}
      Given url baseUrl + '/users' 
      And param q = searchQuery.term 
      When method get 
      Then status 200 
      And match response.users[0].name contains 'example'

3. Reusability & Data-Driven

• Call features/functions: * call read('helpers/common.feature')

• Inline JS: * def calc = function(x,y){ return x+y }

• Data-driven: For more complex looping/data nesting, Karate supports * def data = [...] and multiple scenario calls.

4. Java Runner

Since the Karate Framework uses a Runner file (similar to Cucumber) to execute feature files, much of the structure follows Cucumber standards.

However, unlike Cucumber, Karate doesn’t require step definitions, which provides greater flexibility and simplifies the process. You don’t need to add the additional “glue” code that’s typically required in Cucumber-based setups.

The Runner class is often named TestRunner.java.

import com.intuit.karate.junit4.Karate;
import com.intuit.karate.KarateOptions;
import org.junit.runner.RunWith;

@RunWith(Karate.class)
@KarateOptions(
  features = "classpath:features",
  tags = "~@ignore"
)
public class TestRunner { }

• @RunWith(Karate.class): tells JUnit to use Karate as the test runner.

• features = "classpath:features"Directs Karate on where to find .feature files.

• tags = "~@ignore": the ~ operator excludes all scenarios/features annotated with @ignore

By default, Karate auto-skips any scenario tagged with the special @ignore, so you don’t even need ~@ignore unless you’re explicitly overriding tags.

When You Run Karate Runner File

• Karate scans the features directory in the classpath.

• It includes all scenarios/features except those tagged @ignore.

• The test suite runs them using JUnit 4 via @RunWith(Karate.class).

Common Mistakes to Avoid

• Overusing print instead of assertions

• Hardcoding values that should be parameterized

• Mixing multiple test flows in a single scenario

Watchouts & Best Practices

• Keep scenarios small and focused

• Use tags like @Smoke, @Regression for grouping

• Don’t mix @CucumberOptions (deprecated in Karate) with @KarateOptions – stick to Karate’s own annotation only

• Limit tags and runner configs to the top-level feature files. Tags on “called” features don’t apply to entry-point filtering

• If you upgrade to JUnit 5 (recommended from Karate 0.9.5 onward), move to @Karate.Test instead of @RunWith, often eliminating @KarateOptions.

Conclusion

A well-structured Karate feature file not only makes your tests easier to read and debug but also ensures they remain maintainable as your project scales. By following best practices like modularizing test data, using tags effectively, and keeping scenarios focused, you lay the foundation for a robust and reusable API test suite.

As you continue exploring Karate DSL, adopting these practices will help you write cleaner, more efficient scripts that are easy for your team to understand and extend.

Source: Read More