RUNNING TESTS

Test Configuration

Effective test configuration enables seamless execution across different environments, from local development to CI/CD pipelines. Karate provides flexible configuration mechanisms to adapt to various testing scenarios.

Environment Switching

Control test execution environments using the karate.env system property to dynamically adjust configurations for different stages of your deployment pipeline.

Setting the Environment

The karate.env system property determines which environment-specific configurations to load:

# Maven
mvn test -DargLine="-Dkarate.env=e2e"

# Gradle
./gradlew test -Dkarate.env=e2e

Default Behavior

By default, karate.env returns null when accessed within karate-config.js, allowing you to set default configurations:

function fn() {
  var env = karate.env; // null if not set
  if (!env) {
    env = 'dev'; // default environment
  }

  var config = {
    env: env,
    apiUrl: 'https://api-' + env + '.example.com',
  };

  return config;
}

Running Specific Tests

Execute individual test classes with environment configuration:

# Run specific test class with environment
mvn test -Dtest=CatsRunner -Dkarate.env=staging

# Gradle equivalent
./gradlew test --tests CatsRunner -Dkarate.env=staging

Programmatic Configuration

Set environment properties within Java code for development and testing:

// Direct system property (not recommended for production)
System.setProperty("karate.env", "pre-prod");

// Recommended approach using Runner API
Runner.builder()
  .karateEnv("staging")
  .systemProperty("custom.property", "value")
  .path("classpath:tests")
  .parallel(5);

Environment Tags Integration

Link environments with tags for conditional test execution:

@staging
Scenario: Staging-only test
  * print 'This runs only in staging environment'

@prod @smoke
Scenario: Production smoke test
  * print 'Critical test for production'

Configure tag-based execution:

Runner.builder()
  .karateEnv("staging")
  .tags("@staging", "~@ignore")
  .parallel(5);

Command-Line Options

Maven Configuration

Configure Karate execution through Maven Surefire Plugin:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <argLine>-Dkarate.env=qa -Dkarate.options="--tags @smoke"</argLine>
    <systemPropertyVariables>
      <karate.env>${karate.env}</karate.env>
      <custom.property>${custom.value}</custom.property>
    </systemPropertyVariables>
  </configuration>
</plugin>

Gradle Configuration

Configure Karate in Gradle builds:

test {
  systemProperty "karate.env", System.properties['karate.env'] ?: 'dev'
  systemProperty "karate.options", "--tags @regression"

  // Pass through command-line properties
  systemProperties System.properties.subMap(['karate.env', 'api.key'])
}

CI/CD Integration

Configure for continuous integration environments:

# GitHub Actions example
- name: Run Karate Tests
  run: mvn test -DargLine="-Dkarate.env=${{ github.event.inputs.environment }}"

# Jenkins Pipeline example
stage('Test') {
  steps {
    sh 'mvn test -Dkarate.env=${ENV_NAME} -Dkarate.options="--tags @${TEST_SUITE}"'
  }
}

System Properties

Common Properties

Property	Description	Example
karate.env	Environment name	staging, prod
karate.config.dir	Config directory path	/opt/config
karate.options	Command-line options	--tags @smoke
karate.threads	Parallel thread count	5
karate.report.dir	Report output directory	target/reports

Custom Properties

Define and access custom system properties:

// In karate-config.js
function fn() {
  var config = {
    apiKey: karate.properties['api.key'] || 'default-key',
    timeout: karate.properties['test.timeout'] || 30000,
    retryCount: parseInt(karate.properties['retry.count'] || '3'),
  };
  return config;
}

# Set custom properties
mvn test -Dapi.key=secret123 -Dtest.timeout=60000

Performance Optimization

Connection Pooling

Configure connection reuse for better performance:

function fn() {
  var config = {
    // Connection settings
    connectTimeout: 30000,
    readTimeout: 60000,
    maxConnections: 50,
  };

  // Configure at runtime
  karate.configure('connectTimeout', config.connectTimeout);
  karate.configure('readTimeout', config.readTimeout);

  return config;
}

Retry Configuration

Configure retry behavior for resilient tests:

* configure retry = { count: 3, interval: 1000 }

# Or in karate-config.js
* karate.configure('retry', { count: 3, interval: 1000 })

Best Practices

Environment Isolation

• Keep environment-specific configs separate
• Never commit sensitive data to version control
• Use environment variables for secrets
• Validate configurations on startup

Configuration Hierarchy

1. System properties (highest priority)
2. Environment-specific config files
3. Base configuration file
4. Default values (lowest priority)

Testing Configuration

Feature: Configuration validation

Background:
  * def config = karate.env
  * print 'Running in environment:', config

Scenario: Validate environment setup
  * match config != null
  * assert apiUrl.startsWith('https://')
  * assert timeout > 0

Troubleshooting

Common Issues

Environment not loading:

# Verify property is set
mvn test -X | grep karate.env

# Check in test
* print 'Environment:', karate.env

Configuration conflicts:

// Debug configuration loading
function fn() {
  karate.log('Loading config for env:', karate.env);
  karate.log('System properties:', karate.properties);
  // ... rest of config
}

Property not accessible:

# Use karate.properties for custom properties
* def customValue = karate.properties['custom.property']
* print 'Custom property:', customValue

Next Steps

• Explore Core Syntax > Configuration for environment-specific files
• Learn about Parallel Execution configuration
• Review Test Tags and Filtering for conditional execution