Skip to content

Cucumber Migration

behave-gen migrate converts a Cucumber (Java) project to a Behave project layout by copying .feature files and emitting a migration report.

Usage

behave-gen migrate path/to/cucumber-project --out-dir migrated

What it does

  1. Scans the source directory for .feature files (typically under src/test/resources/features/).
  2. Copies each .feature file into the output directory, preserving the directory structure.
  3. Reports the number of migrated files, any skipped files, and warnings about Java step definitions that need manual translation.

What it does not do

  • Does not translate Java step definitions to Python. Java step files (*Steps.java) are detected and reported as a warning. Use behave-gen add steps --lib <http|auth> to generate Python step definitions, or write them manually.
  • Does not convert Gherkin syntax. Cucumber and Behave both use Gherkin, so .feature files are compatible as-is. The only differences are in step definitions, not feature files.

Example

Source Cucumber project:

cucumber-project/
  src/
    test/
      java/
        com/
          example/
            LoginSteps.java
      resources/
        features/
          login.feature
          checkout.feature

Run migration:

behave-gen migrate cucumber-project --out-dir migrated

Output:

Migrated feature migrated/features/src/test/resources/features/checkout.feature
Migrated feature migrated/features/src/test/resources/features/login.feature

Migrated 2 feature file(s).
migrate: warning: Found 1 Java step definition file(s).
Use 'behave-gen add steps --lib <http|auth>' to generate Python step definitions.

Result:

migrated/
  features/
    src/
      test/
        resources/
          features/
            login.feature
            checkout.feature

After migration

  1. Add step definitions:
cd migrated
behave-gen add steps --lib http
behave-gen add steps --lib auth
  1. Check for undefined steps:
behave-gen check
  1. Run tests:
behave

Options

Option Default Description
SOURCE_DIR required Cucumber project to migrate.
--out-dir migrated Output directory for the Behave project.