Jubilant Bdd Migration

Jubilant BDD Migration (gherkinator-controlled)

Convert an external charm repo's existing pytest integration tests (written with jubilant) into Gherkin feature files backed by pytest-jubilant-bdd. The workflow is driven by gherkinator: test plans are authored once as structured YAML, validated against a strict schema, and transpiled into .feature files that the BDD framework executes.

Use this skill when

• The user asks to "migrate", "convert", "Gherkin-ize", or "move to BDD" tests in a Juju charm repository.
• The target repo has tests/integration/*.py using jubilant directly (e.g. jubilant.temp_model(), juju.deploy(), juju.wait()) and no feature files.
• The repo contains charm markers (charmcraft.yaml, metadata.yaml, src/charm.py).

Do NOT use this skill when

• Working inside the pytest-jubilant-bdd plugin repo itself (that repo has its own unit-testing skill for testing the framework's handlers).
• The user only wants to fix or extend existing BDD tests, not migrate from non-BDD tests.
• The target repo does not already use jubilant; this is a migration skill, not a greenfield authoring guide.

DOs

• DO install gherkinator (snap or from source) before authoring plans.
• DO initialize test-plan.yaml via gherkinator init and edit it with gherkinator edit (surfaces schema hints and validates on save).
• DO run gherkinator validate after every YAML change.
• DO regenerate .feature files with gherkinator generate --format gh after every YAML change.
• DO start new plans with status: planned; flip to implemented only after the BDD suite is green for that plan.
• DO load each generated .feature in its own test_*.py via scenarios("features/<name>.feature").
• DO use context.wait() for polling in custom steps; drop tenacity.Retrying.
• DO consult the reusable-step-handler skill in the pytest-jubilant-bdd repo for the canonical Context API when authoring custom steps.
• DO keep the original non-BDD tests in place until the BDD suite is fully green.

DO NOTs

• DO NOT hand-edit generated .feature files — they are overwritten on every gherkinator generate.
• DO NOT import step handlers from pytest_jubilant_bdd._main; the plugin auto-registers them via the pytest11 entry point, and they are not part of the public API.
• DO NOT define a juju fixture in conftest.py — the plugin provides context.
• DO NOT invent type, status, or risk values outside the enums enforced by gherkinator validate.
• DO NOT modify production charm code in the target repo to make a test pass — pause and ask the user.
• DO NOT bypass gherkinator validate by editing the generated .feature file to silence schema errors.

Framework facts (source of truth)

These are verified against the installed pytest-jubilant-bdd package.

• Auto-registration. The plugin registers via the pytest11 entry point (pyproject.toml → pytest_jubilant_bdd._main). Installing the package makes all built-in @given/@when/@then handlers available to pytest-bdd. Consumers never import the step handlers.
• Public API (from pytest_jubilant_bdd import ...): Context, assertions, flexible, make_dict, make_list. Only these are importable. Context is the fixture type; the rest are for authoring custom steps.
• The context fixture (session-scoped, provided by the plugin) yields a Context object. It replaces a hand-rolled juju fixture. Do not define a juju fixture in the charm repo's conftest.py.
• CLI options registered by the plugin: --juju-bdd-no-teardown (skip model teardown) and --juju-bdd-wait-timeout <sec> (default 180s).
• Dependencies (the plugin pulls these in): jubilant ~= 1.0, pytest-bdd ~= 8.0. Requires Python >=3.12.

Authoritative reference: the context fixture API

The full Context API — context.get_juju(), context.get_app() / get_apps() / get_unit(), the action_results / exec_results stacks, context.wait() polling semantics, and the assertions.app / .model / .unit namespaces — is documented authoritatively in the reusable-step-handler skill in the pytest-jubilant-bdd repo:

• Repo path: .agents/skills/reusable-step-handler/SKILL.md
• Web: https://github.com/canonical/pytest-jubilant-bdd/blob/main/.agents/skills/reusable-step-handler/SKILL.md

That skill is the source of truth for the context fixture and for how reusable handlers integrate with it. Consult it whenever you need the exact signature, return type, or error class for a Context method, or when authoring custom steps. The migration skill only restates the high-level patterns needed to map existing jubilant code onto built-in steps (see reference.md).

Reusable step reference

Exact Gherkin phrasing (single quotes; [...] marks optional, reorderable clauses; %...% blocks are raw-regex units handled by the flexible parser).

Given (setup):

When (actions):

Then (attestation):

Status values are fixed by the framework; do not invent new ones in feature files.

Gherkinator integration (controller for test plans)

The migration is driven by gherkinator, a CLI that treats YAML test plans as the single source of truth and generates .feature files from them. Authors edit YAML; .feature files are generated artifacts (regenerate them whenever the YAML changes — never hand-edit them).

Why gherkinator

• Schema validation. gherkinator validate enforces required fields and allowed enum values (type, status, risk) before any .feature file is generated.
• Syntax-correct output. gherkinator generate --format gh runs the generated text through the official Cucumber Gherkin parser, so the emitted .feature files are always syntactically valid.
• Structured metadata. The type, status, and risk fields of each TestPlan become Gherkin tags (@functional, @planned, @stable) and support --risk / --status filtering for incremental migration.
• Single source of truth. One test-plan.yaml can contain many features separated by ---. Each generates one <feature>.feature file.

Install gherkinator

# Snap (recommended)
sudo snap install gherkinator --classic

# From source
git clone https://github.com/canonical/gherkinator.git
cd gherkinator && go build -o gherkinator .

Commands used in this skill

YAML field mapping (TestPlan → BDD)

The TestPlan schema (full reference in reference.md) maps to Gherkin like this:

A scenario is rendered as Scenario: <title> when it has no examples row, or as Scenario Outline: <title> with Examples: when it does.

Migration workflow

1. Inspect the target repo. Locate tests/integration/**/*.py, conftest.py, charmcraft.yaml, metadata.yaml. Identify which tests use jubilant directly. Reference the pattern-mapping table in reference.md.

2. Map each test to a scenario. For every def test_*(...):

   • Setup (deploys, models, config, integrations) → Given steps.
   • Actions (juju.run, juju.exec, config changes) → When steps.
   • Assertions (status, messages, command output, action results) → Then steps.
   • Note any test that does NOT map to a built-in step — that becomes a custom step.
   • Group tests into logical features (one .feature file per group: deployment, integration, operations, actions).

3. Initialize gherkinator. Run from the repo root:

   gherkinator init tests/integration/features --name test-plan
   

   This creates tests/integration/features/test-plan.yaml as an empty multi-document file. It is the single source of truth for every migration scenario in this repo.

4. Create YAML test plans. Author one TestPlan document per logical feature in tests/integration/features/test-plan.yaml. Open it with:

   gherkinator edit tests/integration/features/test-plan.yaml
   

   The editor opens with a leading comment that documents the schema. For each plan document:

   • feature: human-readable name (e.g. "Slurmctld deployment").
   • type: functional for typical charm tests; reliability for HA / multi-unit; performance for benchmarks; solution for end-to-end user workflows.
   • status: planned for newly migrated tests.
   • risk: choose based on criticality (see field-mapping table above).
   • description: 1–3 sentences explaining what the feature covers.
   • background: shared Given steps (typically Given I add model 'test').
   • scenarios: one entry per original test. First line is the scenario title; subsequent lines are Given/When/Then steps using the exact phrasing from the step reference table.

   See examples.md for full YAML test plan examples.

5. Validate and generate. Run gherkinator to confirm the YAML is schema-compliant, then produce .feature files:

   gherkinator validate tests/integration/features/test-plan.yaml
   gherkinator generate --format gh tests/integration/features/test-plan.yaml \
     --output-dir tests/integration/features
   

   The generated files (<feature>.feature) live alongside the YAML. Fix any validate errors in the YAML and re-run; do not hand-edit .feature files — they will be overwritten on the next generate.

   Tip: during incremental migration, generate only a subset using --status planned --risk edge and commit plan-by-plan.

6. Write custom step definitions (only for domain logic with no built-in equivalent) in tests/integration/test_<feature>.py. Each module loads its scenarios with scenarios("features/<name>.feature") and defines any custom steps the framework doesn't already provide. Use the context fixture and context.wait() for polling. Templates are in examples.md.

7. Configure the repo. Add pytest-jubilant-bdd to the integration test dependencies. Do not redefine a juju fixture — the plugin provides context. Do not import step handlers. See reference.md for pyproject.toml and conftest.py snippets.

8. Run the BDD suite and confirm scenarios pass:

   just integration
   

   Fix-and-rerun until green. After the suite is green for a given plan, flip the corresponding YAML status field from planned to implemented and re-run gherkinator generate so the regenerated .feature file carries the @implemented tag.

Stop and report if

• gherkinator validate reports a schema error — fix the YAML field, not the .feature output.
• A built-in step's phrasing doesn't match the Gherkin you wrote — re-read the reference table; built-in patterns are fixed.
• You're tempted to edit production code in the target charm repo to make a test pass — pause and ask the user.
• The target repo's jubilant API differs materially from the patterns in reference.md — confirm the jubilant version and adjust custom-step guidance accordingly.
• A test needs a step the framework genuinely doesn't provide — propose a custom step to the user rather than forcing a built-in to fit.

Evaluation prompts

Use these to check skill routing and behavior.

Positive (should trigger):

• "Migrate the integration tests in tests/integration/test_charm.py to BDD with pytest-jubilant-bdd."
• "Convert this repo's jubilant tests to Gherkin feature files using gherkinator."
• "Use gherkinator to scaffold BDD feature files for this charm."

Near-miss (should NOT trigger):

• "Write a unit test for the add_model step handler in pytest-jubilant-bdd."
• "Explain how Context.wait() polls."

Edge case:

• "Migrate these tests, but preserve @pytest.mark.order across feature files and keep the action-result assertions."

Supporting files

• reference.md — gherkinator TestPlan schema, command reference, pattern-mapping table, conftest.py/pyproject.toml snippets, CLI options, ordering, verification checklist, troubleshooting.
• examples.md — full before/after migrations showing the YAML → gherkinator → .feature pipeline and custom-step templates.

Related resources

• gherkinator: https://github.com/canonical/gherkinator
• pytest-jubilant-bdd: https://github.com/canonical/pytest-jubilant-bdd
• jubilant: https://github.com/canonical/jubilant
• pytest-bdd: https://pytest-bdd.readthedocs.io/
• Gherkin reference: https://cucumber.io/docs/gherkin/reference/