Setting Up a Karate Project with Maven

Every Karate project starts with Maven. That might feel heavyweight if you were expecting a no-code tool, but Maven's role here is minimal: it downloads the Karate dependency and provides a command (mvn test) to run your feature files. You write one pom.xml once, and after that you never touch Java tooling again — the rest is .feature files and one JavaScript config.

The pom.xml — one dependency

Karate ships everything it needs in a single artifact. Add this to a fresh pom.xml:

<dependencies>
    <dependency>
        <groupId>com.intuit.karate</groupId>
        <artifactId>karate-junit5</artifactId>
        <version>1.4.1</version>
        <scope>test</scope>
    </dependency>
</dependencies>
 
<build>
    <testResources>
        <testResource>
            <directory>src/test/java</directory>
            <excludes>
                <exclude>**/*.java</exclude>
            </excludes>
        </testResource>
    </testResources>
</build>

One dependency — no separate HTTP client, no assertion library, no reporting plugin. Karate bundles all of them. The <testResources> block tells Maven to include .feature files and .json files that sit alongside your Java sources in src/test/java.

For the Java version, set <maven.compiler.source> and <maven.compiler.target> to 11 or higher. Karate 1.4 requires Java 11 at minimum; Java 17 is a safe default.

Project structure

The layout this course uses:

karate-tests/
├── pom.xml
└── src/test/java/
    ├── karate-config.js          ← global configuration
    └── users/
        ├── UsersRunner.java      ← JUnit 5 runner (3 lines)
        ├── users.feature         ← test feature file
        └── test-data.json        ← test data (optional)

Feature files live next to the runner class that points at them, inside src/test/java. There is no src/test/resources in a typical Karate project — the <testResources> configuration above makes Maven pick up non-Java files from src/test/java directly.

Organise by API resource or by feature area. A team testing a Users API and an Orders API might have users/ and orders/ packages, each with their own runner and feature files.

The runner class

This is the only Java you write in a Karate project:

package users;
 
import com.intuit.karate.junit5.Karate;
 
class UsersRunner {
    @Karate.Test
    Karate testUsers() {
        return Karate.run("users").relativeTo(getClass());
    }
}

Three lines of code. The @Karate.Test annotation tells JUnit 5 to treat this method as a test entry point. Karate.run("users") finds the users.feature file in the same package. relativeTo(getClass()) resolves the path relative to this runner's location on disk. That's the full extent of Java in test authoring.

To run all feature files in a package (not just one), pass "." instead of a file name: Karate.run(".").

karate-config.js — global configuration

karate-config.js lives at the root of src/test/java/ (not inside a package subfolder). Karate automatically runs it before every feature file and makes the returned object available as variables:

function fn() {
    var config = {
        baseUrl: 'https://api.staging.myapp.com'
    };
 
    var env = karate.env; // set via -Dkarate.env on the command line
    if (env == 'production') {
        config.baseUrl = 'https://api.myapp.com';
    }
 
    return config;
}

Inside any feature file, baseUrl is now available without any import:

Scenario: Get all users
  Given url baseUrl + '/users'
  When method get
  Then status 200

This is the standard Karate pattern for environment-aware tests. The URL is never hardcoded in the feature file — it comes from config, which can be switched at runtime.

Running tests

From the terminal:

mvn test

With a specific environment:

mvn test -Dkarate.env=production

Running a specific feature file only (by tag):

mvn test -Dkarate.options="--tags @smoke"

From IntelliJ: right-click the runner class → Run, or right-click directly on a .feature file → Run. The Karate IntelliJ plugin adds syntax highlighting and individual scenario run buttons inside .feature files — install it before writing your first test.

The setup flow, step by step

⚠️ Common mistakes

• Forgetting the <testResources> block. Without it, Maven compiles .java files in src/test/java but ignores .feature files next to them. The runner finds no tests and reports zero executed. This is the most common setup failure for new Karate projects.
• Placing karate-config.js inside a package subfolder. The file must be at the root of src/test/java/, not inside users/ or any other package. Karate looks for it by classpath root. If it's nested, it won't load, and all your baseUrl references will fail with an undefined variable error.
• Using karate-junit4 when the project expects JUnit 5. The artifact names are karate-junit4 and karate-junit5 — they are not interchangeable. If your pom.xml has JUnit 5's junit-jupiter elsewhere, use karate-junit5. Mixing them produces class-not-found errors at runtime that look unrelated to Karate.

🎯 Practice task

Get a runnable Karate project onto disk. 30–40 minutes.

1. Create a new Maven project in IntelliJ with GroupId com.mycompany.karatetests and ArtifactId karate-tests. Confirm the project structure includes src/test/java.
2. Replace the generated pom.xml with the dependency and <testResources> blocks from this lesson. Set Java source/target to 17. Click "Load Maven Changes". Run mvn dependency:resolve and confirm karate-junit5 appears in the output.
3. Create src/test/java/karate-config.js. Return { baseUrl: 'https://jsonplaceholder.typicode.com' }. This free fake API works without authentication.
4. Create the package users under src/test/java. Add UsersRunner.java — copy the three-line example above, changing the package to users.
5. Create users/users.feature with a single scenario: GET /users, assert status 200. Run the runner from IntelliJ. The test should go green.
6. Add -Dkarate.env=staging to the IntelliJ run configuration. In karate-config.js, add a branch that sets a different baseUrl when env == 'staging'. Confirm the variable switches correctly by printing it: * print baseUrl as the first step in your scenario.
7. Stretch: install the Karate IntelliJ plugin. Open users.feature and use the play button next to an individual scenario. Notice that you can run one scenario without running the whole feature — useful when debugging a single failing test.

Next lesson: writing your first feature file — the full set of built-in keywords, the Background block, and how Karate's step keywords differ from Cucumber's.