Skip to content

Configuration

behave-pool adds several CLI options and behave.ini settings to control parallel execution. This page documents every option with examples.

CLI options

--parallel N
Default 1
Type integer
Description Number of worker processes. 1 = sequential passthrough (standard Behave). 
# 4 worker processes
behave --runner=parallel --parallel 4 features/

# Sequential (same as standard behave)
behave --runner=parallel --parallel 1 features/

# Auto-detect from --jobs (behave's built-in option)
behave --runner=parallel --jobs 4 features/

--parallel vs --jobs

behave-pool maps Behave's built-in --jobs option to --parallel. You can use either. If both are specified, --jobs takes precedence.

--parallel-scheme
Default feature
Choices feature
Description Parallelization unit: one work unit per feature file. 
# Feature-level parallelization (default)
behave --runner=parallel --parallel 4 --parallel-scheme feature features/

Scenario scheme

--parallel-scheme scenario is recognized but not yet implemented. It will raise NotImplementedError. Scenario-level parallelization is planned for a future release.

--parallel-balance
Default lpt
Choices lpt, fifo
Description Work unit ordering strategy.

Longest Processing Time first. Features are sorted descending by their historical duration so the slowest features start first, minimizing total wall-clock time.

behave --runner=parallel --parallel 4 --parallel-balance lpt features/

Requires a timing file (see --parallel-timing-file). On the first run, when no timing data exists, all durations default to 0.0 and LPT ordering has no effect.

First In, First Out. Work units are dispatched in the order features are discovered (alphabetical by filename).

behave --runner=parallel --parallel 4 --parallel-balance fifo features/

--parallel-timing-file
Default .behave-pool-timing.json
Type string (file path)
Description Path to the JSON file storing historical durations for LPT balancing. 
# Custom timing file location
behave --runner=parallel --parallel 4 \
    --parallel-timing-file .my-timings.json \
    features/

The timing file is a simple JSON object mapping work unit IDs to durations in seconds:

{
  "feature:features/login.feature": 1.23,
  "feature:features/checkout.feature": 0.45,
  "feature:features/search.feature": 2.10
}

Gitignore

Add .behave-pool-timing.json to your .gitignore — it's a local optimization artifact, not something you should commit.

--parallel-report
Default behave-pool-report.json
Type string (file path)
Description Path to the unified JSON report file. After all workers finish, their individual reports are merged into a single Behave-compatible JSON array. 
# Default report path
behave --runner=parallel --parallel 4 features/
# → writes behave-pool-report.json

# Custom report path
behave --runner=parallel --parallel 4 \
    --parallel-report reports/run-2024-01-15.json \
    features/

The report follows the behave-modern-json-report ExecutionReport schema (v1.1.0), a rich structured format with execution metadata, statistics, environment info, and full feature/scenario/step details:

{
  "schemaVersion": "1.1.0",
  "execution": {
    "executionId": "exec-a1b2c3...",
    "status": "passed",
    "duration": 12.345,
    "startTime": "2024-01-15T10:30:00.123Z",
    "endTime": "2024-01-15T10:30:12.468Z"
  },
  "statistics": {
    "features": 3,
    "scenarios": 15,
    "steps": 42,
    "passed": 40,
    "failed": 0,
    "skipped": 2,
    "passRate": 1.0,
    "duration": 12.345,
    "byTag": {
      "@smoke": { "count": 5, "duration": 3.2, "passed": 5 }
    }
  },
  "environment": {
    "pythonVersion": "3.12.1",
    "behaveVersion": "1.2.6",
    "platform": "linux",
    "os": "Linux",
    "ciProvider": "github-actions",
    "gitBranch": "main",
    "gitCommit": "a1b2c3d"
  },
  "features": [
    {
      "id": "feature-abc123",
      "name": "Login",
      "description": "User authentication flows",
      "filename": "features/login.feature",
      "line": 1,
      "tags": ["@smoke"],
      "status": "passed",
      "duration": 1.23,
      "scenarios": [
        {
          "id": "scenario-def456",
          "name": "Successful login",
          "featureId": "feature-abc123",
          "status": "passed",
          "duration": 0.8,
          "steps": [
            {
              "id": "step-ghi789",
              "keyword": "Given ",
              "text": "I am on the login page",
              "status": "passed",
              "duration": 0.2,
              "error": null,
              "attachments": [],
              "logs": []
            }
          ]
        }
      ]
    }
  ],
  "metadata": {}
}

Downstream tools

The report uses the same schema as behave-modern-json-report, so any tool built for that ecosystem (HTML formatters, dashboards, AI analyzers) can consume the parallel report directly — no conversion needed.

behave.ini configuration

All options can be set permanently in behave.ini:

[behave]
parallel = 4
parallel-scheme = feature
parallel-balance = lpt
parallel-timing-file = .behave-pool-timing.json
parallel-report = behave-pool-report.json

[behave.runners]
parallel = behave_pool:ParallelRunner

With this configuration, running behave features/ will automatically use 4 worker processes with LPT balancing.

Example: CI vs local development

You can use different behave.ini files for CI and local development:

[behave]
parallel = 8
parallel-balance = lpt

[behave.runners]
parallel = behave_pool:ParallelRunner

[behave]
parallel = 1

[behave.runners]
parallel = behave_pool:ParallelRunner

Environment variables

behave-pool does not introduce any environment variables. All configuration is done through CLI options or behave.ini.

Default values summary

Option Default Choices
--parallel 1 any positive integer
--parallel-scheme feature feature
--parallel-balance lpt lpt, fifo
--parallel-timing-file .behave-pool-timing.json any file path