Skip to main content

Tags

Organize tests and control execution using Gherkin tags. Tags provide powerful meta-data for partitioning tests into categories like smoke, regression, and environment-specific subsets.

Basic Tag Usage​

Add tags above scenarios to categorize and filter tests:

Gherkin
@userApi @positive
Feature: User API Tests

  Background:
    * url 'https://jsonplaceholder.typicode.com'

  @smoke @fast
  Scenario: Quick user lookup
    Given path 'users', 1
    When method get
    Then status 200

  @regression @auth
  Scenario: Simulated user authentication flow
    Given path 'users', 1
    When method get
    Then status 200

  @integration @slow
  Scenario: Simulated cross-system user sync
    Given path 'posts'
    And request
    """
    {
      "userId": 1,
      "title": "User Sync Test",
      "body": "Simulating user sync with post creation."
    }
    """
    When method post
    Then status 201

Running Tests with Tags​

Command Line Filtering​

Command Line
# Run only smoke tests
karate run -t @smoke features/

# Exclude slow tests
karate run -t ~@slow features/

# Run tests with either tag (OR within one -t)
karate run -t @api,@integration features/

# Run tests with both tags (AND via repeated -t)
karate run -t @smoke -t @auth features/

Java teams using Maven/Gradle drive tag filtering through the JUnit 6 runner class. See Command Line — Maven Execution.

Parallel Runner with Tags​

Java
import io.karatelabs.core.Runner;
import io.karatelabs.core.SuiteResult;

@Test
void smokeTests() {
    SuiteResult results = Runner.builder()
            .path("classpath:features")
            .tags("@smoke")
            .parallel(5);

    assertFalse(results.isFailed());
}

@Test
void regressionExcludingSlow() {
    SuiteResult results = Runner.builder()
            .path("classpath:features")
            .tags("@regression", "~@slow") // AND operation
            .parallel(8);

    assertFalse(results.isFailed());
}

Special Built-In Tags​

@ignore Tag​

Skip scenarios without deleting them:

Feature: Work in progress

@ignore
Scenario: Not ready yet * print 'This will not execute'

@ignore @reason=bug-fix-pending
Scenario: Known issue * print 'Skip until bug is fixed'

Scenario: Active test * print 'This will execute normally'

The @ignore tag is automatically excluded - no need to specify ~@ignore.

@ignore with Called Features

Scenarios marked with @ignore are skipped during test execution but can still be called using call or callonce. This is useful for creating reusable helper scenarios.

See Calling Features for examples.

@parallel=false Tag​

Force sequential execution when test independence isn't possible:

Gherkin
@parallel=false
Feature: Database setup
# All scenarios run sequentially

Scenario Outline: Run database setup scripts
  * call read('<featureFile>')

  Examples:
    | featureFile            |
    | create-schema.feature  |
    | insert-data.feature    |
Anti-Pattern

Sequential execution indicates test dependencies. Design independent scenarios when possible.

Environment-Specific Tags​

@env Tag​

Run scenarios only in specific environments:

Gherkin
@env=dev,test
Scenario: Development testing
  * print 'Only runs in dev or test environments'

@env=prod
Scenario: Production health check
  Given path 'health'
  When method get
  Then status 200

@envnot Tag​

Exclude scenarios from specific environments:

Gherkin
@envnot=prod
Scenario: Destructive test
  * print 'Never runs in production'

@envnot=local
Scenario: External service test
  * print 'Requires external dependencies'

Tag Strategies​

Common Tag Categories​

CategoryExamplesPurpose
Contract Testing@positive, @negativeTesting Phases
Execution Phase@smoke, @regression, @integrationCI/CD pipeline stages
Performance@fast, @slow, @loadExecution time management
Business Domain@auth, @payment, @userFeature area organization
Risk Level@critical, @high, @mediumPriority-based testing

Tag Combinations​

Gherkin
Feature: Multi-dimensional tagging

@smoke @auth @fast @critical
Scenario: Critical auth smoke test
# Runs in smoke, auth, fast, and critical test suites

@regression @payment @slow @integration  
 Scenario: Payment integration test 
 # Comprehensive payment workflow testing

Advanced Tag​

Advanced Tag Features​

Tags with Values​

Create structured metadata using key-value tags:

Gherkin
Feature: Advanced Tag Features

@module=auth @priority=high @owner=team-alpha
Scenario: Structured tagging
  * def tagValues = karate.tagValues
  * def module = tagValues.module[0]
  * def priority = tagValues.priority[0]
  * print 'Testing module:', module, 'priority:', priority

Call with Tag Selectors​

Select specific scenarios when calling features:

Gherkin
Feature: Tag-based calling

Background:
  * call read('setup.feature@database')

Scenario: Main test
  * call read('workflows.feature@name=createUser')
  * call read('cleanup.feature@cleanup')

Debugging Tag Issues​

To troubleshoot tag-related problems:

  • Use karate.tags to log applied tags: * print karate.tags.
  • Verify tag filtering in karate.log with .systemProperty("log.level", "DEBUG").
  • Run a single feature with specific tags to isolate issues: karate run -t @smoke classpath:feature.feature.

Tag-Based Reporting​

Filter reports by tags for analysis:

  • Generate tag-specific reports: Runner.builder().path("classpath:features").tags("@smoke").outputCucumberJson(true).parallel(1).
  • Use karate-timeline.html to view tag distribution across threads.
  • In CI, archive tag-based reports: target/karate-reports/smoke.cucumber.json.

CI/CD Integration with Tags​

Example for GitHub Actions to run tagged tests:

Tag Best Practices​

Clear Naming Conventions​

# Good: Consistent, descriptive tags
@smoke @auth @fast
@regression @payment @integration
@critical @security @compliance

# Avoid: Inconsistent naming

@Test1 @SMOKE @Payment @fast_test

Balanced Tag Strategy​

  • Keep it simple: 3-5 tag dimensions maximum
  • Be consistent: Establish naming conventions
  • Document strategy: Maintain tag definitions
  • Regular cleanup: Remove unused tags
  • Optimize for performance: Avoid complex tag expressions (e.g., (@smoke or @critical) and not @flaky) for large suites.

Scenario Outline and Examples Tags​

Tags on Examples: blocks are evaluated per generated scenario, not per outline. This means different Examples blocks within the same outline can have different tags, and tag filters apply independently to each block's rows.

Gherkin
@smoke
Scenario Outline: Order processing - <type>
  * def orderType = '<type>'
  * print 'Processing:', orderType

  Examples:
    | type     |
    | standard |
    | express  |

  @slow
  Examples:
    | type  |
    | bulk  |
    | batch |

Running with --tags @smoke --tags ~@slow executes only standard and express — the @slow Examples block is excluded while the untagged block runs normally.

Tag Inheritance for Outlines​

The effective tags for each generated scenario are the merge of: feature tags + outline tags + that row's Examples block tags. Tags from other Examples blocks do not apply:

SourceTagsApplies to
Feature@apiAll scenarios in the feature
Scenario Outline@smokeAll rows from all Examples blocks
Examples block@slowOnly rows from that specific block

A row from the untagged Examples block above has effective tags @api @smoke. A row from the @slow block has effective tags @api @smoke @slow.

Common Gotchas​

  • Feature-level tags: Inherited by all scenarios in the feature
  • Tag syntax: Must start with @ and contain no spaces
  • Case sensitivity: Tags are case-sensitive (@Smoke ≠ @smoke)
  • Inheritance: Scenario tags combine with feature-level tags; for outlines, each Examples block's tags apply only to its own rows
  • Performance: Complex tag filters can slow test selection in large suites

Next Steps​

Organize tests effectively with tags:

On This Page