or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.cucumber/cucumber-expressions@19.0.x
tile.json

tessl/maven-io-cucumber--cucumber-expressions

tessl install tessl/maven-io-cucumber--cucumber-expressions@19.0.0

Cucumber Expressions are simple patterns for matching Step Definitions with Gherkin steps

index.mddocs/

Cucumber Expressions

Cucumber Expressions is a Java library that provides an intuitive alternative to Regular Expressions for pattern matching in behavior-driven development (BDD) test automation. It enables developers to write readable step definitions for Gherkin scenarios using a simpler syntax with built-in parameter types (int, float, string, word) that automatically convert matched text to strongly-typed arguments.

Package Information

  • Package Name: cucumber-expressions
  • Group ID: io.cucumber
  • Artifact ID: cucumber-expressions
  • Version: 19.0.0
  • Language: Java
  • Installation:
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-expressions</artifactId>
    <version>19.0.0</version>
</dependency>

Quick Start

import io.cucumber.cucumberexpressions.*;
import java.util.*;

// Create registry and factory
ParameterTypeRegistry registry = new ParameterTypeRegistry(Locale.ENGLISH);
ExpressionFactory factory = new ExpressionFactory(registry);

// Create expression and match text
Expression expr = factory.createExpression("I have {int} cucumbers");
Optional<List<Argument<?>>> match = expr.match("I have 42 cucumbers");

// Extract value
if (match.isPresent()) {
    Integer count = (Integer) match.get().get(0).getValue();
    System.out.println("Count: " + count); // 42
}

→ Complete Quick Start Guide

Core Components

Expression System

Create and match text patterns using Cucumber Expression or Regular Expression syntax.

package io.cucumber.cucumberexpressions;

public final class ExpressionFactory {
    public ExpressionFactory(ParameterTypeRegistry parameterTypeRegistry);
    public Expression createExpression(String expressionString);
}

public interface Expression {
    Optional<List<Argument<?>>> match(String text, Type... typeHints);
    Pattern getRegexp();
    String getSource();
}

→ Detailed Expression Reference

Parameter Types

Define custom parameter types for automatic type conversion.

package io.cucumber.cucumberexpressions;

public final class ParameterType<T> {
    public ParameterType(String name, String regexp, Class<T> type, Transformer<T> transformer);
    public static <E extends Enum<E>> ParameterType<E> fromEnum(Class<E> enumClass);
}

public final class ParameterTypeRegistry {
    public ParameterTypeRegistry(Locale locale);
    public void defineParameterType(ParameterType<?> parameterType);
}

→ Parameter Types Reference

Transformers

Convert matched strings to Java types.

package io.cucumber.cucumberexpressions;

@FunctionalInterface
public interface Transformer<T> {
    T transform(String arg) throws Throwable;
}

@FunctionalInterface
public interface CaptureGroupTransformer<T> {
    T transform(String[] args) throws Throwable;
}

→ Transformers Reference

Matching System

Extract typed arguments with position information.

package io.cucumber.cucumberexpressions;

public final class Argument<T> {
    public Group getGroup();
    public T getValue();
    public Type getType();
    public ParameterType<T> getParameterType();
}

public final class Group {
    public String getValue();
    public int getStart();
    public int getEnd();
}

→ Matching Reference

Built-In Parameter Types

TypeSyntaxJava TypeExample
Integer{int}Integer42, -19
Float{float}Float3.6, -9.2
Double{double}Double3.14159
String{string}String"hello", 'world'
Word{word}Stringhello, user123
Byte{byte}Byte127
Short{short}Short1000
Long{long}Long1234567890
BigInteger{biginteger}BigInteger999999999999
BigDecimal{bigdecimal}BigDecimal99.99
Anonymous{}ObjectAny text

Key Features

Cucumber Expression Syntax

Simple, readable pattern syntax with parameter placeholders:

  • I have {int} cucumbers - matches integers
  • I have {string} in my bag - matches quoted strings
  • I have {int} cucumber(s) - optional text with parentheses
  • in my belly/stomach - alternative text with forward slash

Regular Expression Support

Expressions starting with ^ or ending with $ use regex mode:

  • ^I have (\\d+) cucumbers$ - regex with anchors
  • Automatic type conversion based on pattern matching

Localized Number Parsing

Built-in support for locale-specific number formats:

  • English: 1,234.56 (comma thousands, period decimal)
  • French: 1.234,56 (period thousands, comma decimal)
  • Configurable via ParameterTypeRegistry(Locale)

Expression Generation

Automatically generate expressions from example text:

CucumberExpressionGenerator generator = new CucumberExpressionGenerator(registry);
List<GeneratedExpression> expressions = generator.generateExpressions("I have 42 cucumbers");
// Suggests: "I have {int} cucumbers"

→ Expression Generation Reference

Thread Safety

CRITICAL:

  • ParameterTypeRegistry: NOT thread-safe during modification
  • ExpressionFactory: Thread-safe after construction
  • Expression instances: Thread-safe and immutable
  • Best Practice: Configure registry at startup, then use concurrently
// Safe concurrent usage
public class ExpressionManager {
    private final ExpressionFactory factory;
    
    public ExpressionManager() {
        ParameterTypeRegistry registry = new ParameterTypeRegistry(Locale.ENGLISH);
        registry.defineParameterType(/* custom types */);
        this.factory = new ExpressionFactory(registry);
    }
    
    // Thread-safe
    public Optional<List<Argument<?>>> match(String pattern, String text) {
        Expression expr = factory.createExpression(pattern);
        return expr.match(text);
    }
}

Exception Handling

All exceptions extend CucumberExpressionException:

  • UndefinedParameterTypeException - Parameter type not registered
  • AmbiguousParameterTypeException - Multiple types match same pattern
  • DuplicateTypeNameException - Type name already registered

→ Exception Handling Reference

Documentation Resources

Guides

Examples

Reference

Common Use Cases

Step Definition Matching

Expression expr = factory.createExpression("User {string} logs in with {string}");
Optional<List<Argument<?>>> match = expr.match("User \"john@example.com\" logs in with \"secret123\"");

Custom Type Registration

ParameterType<Email> emailType = new ParameterType<>(
    "email", "[\\w.]+@[\\w.]+", Email.class, Email::new
);
registry.defineParameterType(emailType);

Enum Types

enum Status { ACTIVE, INACTIVE }
ParameterType<Status> statusType = ParameterType.fromEnum(Status.class);
registry.defineParameterType(statusType);

Performance Tips

  • Reuse expressions: Create once, match many times
  • Cache expressions: Use ConcurrentHashMap for frequently used patterns
  • Register types at startup: Complete all registration before concurrent use
  • Optimize transformers: Keep transformation logic lightweight

Migration from Regular Expressions

Regular ExpressionCucumber Expression
(\\d+){int}
(.+){string}
(\\S+){word}
(\\d+\\.\\d+){float}

Quick Reference

Core Imports

import io.cucumber.cucumberexpressions.ExpressionFactory;
import io.cucumber.cucumberexpressions.ParameterTypeRegistry;
import io.cucumber.cucumberexpressions.ParameterType;
import io.cucumber.cucumberexpressions.Expression;
import io.cucumber.cucumberexpressions.Argument;
import io.cucumber.cucumberexpressions.Transformer;

Typical Workflow

  1. Create ParameterTypeRegistry with locale
  2. Register custom parameter types (optional)
  3. Create ExpressionFactory with registry
  4. Create expressions from strings
  5. Match text and extract typed arguments

Version Information

  • Current Version: 19.0.0
  • API Stability: Stable (except Parsing API - experimental)
  • Java Compatibility: Java 8+
  • Dependencies: org.jspecify (annotations)

Need Help?