BDD How-to Guides#

Step-by-step instructions for creating and implementing BDD tests.

Create a BDD test in JIRA#

This workflow creates tests linked to SKA requirements for full traceability.

1. Identify the requirement#

Start with an SKA requirement or Feature:

  • Use an existing requirement (L1, L2, interface, or verification)

  • Or create a new verification requirement in the VTS project

If creating a new requirement, label it with the PI (Program Increment) in which you plan to implement it.

2. Create a Test Set#

  1. Create a JIRA issue of type Test Set in the XTP project

  2. Add a fix version for the relevant PI (optional)

  3. Link the Test Set to your requirement using the tests relationship

    • From the requirement side, use tested by instead

3. Create individual tests#

For each test in your Test Set:

  1. Create an issue of type Test in the XTP project

  2. Add fix version (optional)

  3. Click the Test Details tab

  4. Set:

    • Test type: Cucumber

    • Cucumber type: scenario

    • Cucumber scenario: Write your Gherkin steps (given, when, then)

  5. Link your test to the relevant Test Set

Tip

Reuse existing tests by linking them to new Test Sets. Check existing tests in XTP before creating duplicates.

4. Export the feature file#

After defining all tests for the Test Set:

  1. Open the Test Set in JIRA

  2. Click the More dropdown menu

  3. Select Export to Cucumber

  4. Save the .feature file

Repeat for each Test Set you need to exercise.

Implement tests with pytest-bdd#

Add the exported .feature file to your GitLab repository and implement the test steps.

1. Set up your test file#

Create a test module that imports pytest-bdd and loads your scenarios:

from pytest_bdd import given, when, then, scenarios, parsers
import pytest

# Load scenarios from the feature file
scenarios('path/to/your_test.feature')

# Create a fixture to pass data between steps
@pytest.fixture
def result():
    return {}

2. Write step definitions#

Annotate your test methods with Gherkin keywords:

@given('I have an SDPSubarray device')
def subarray_device(devices, result):
    """Get a subarray device for testing."""
    result['device'] = devices.get_device(DEVICE_NAME)
    return result['device']

@when('I set the device state to ON')
def set_device_state(result):
    """Set the device to ON state."""
    result['device'].on()

@then('the device state is ON')
def check_device_state(result):
    """Verify the device is in ON state."""
    assert result['device'].state == 'ON'

3. Reuse steps across tests#

Share step definitions across multiple tests by placing common steps in a conftest.py file:

# conftest.py
from pytest_bdd import given

@given('I have an SDPSubarray device')
def subarray_device(devices):
    """Shared step - available to all tests in this directory."""
    return devices.get_device(DEVICE_NAME)

Handle parameterised tests#

Use the parsers module for tests with variable inputs:

from pytest_bdd import when, then, parsers

@when(parsers.parse('OET create is given a {file} that does not exist'))
def file_not_found(file, result):
    """Attempt to create with non-existent file."""
    result['file'] = file

@then(parsers.parse('the OET returns an {error}'))
def check_error(error, result):
    """Verify the correct error is returned."""
    assert error in str(result['exception'])

Feature files support Examples tables for multiple test cases:

@XTP-1156
Scenario Outline: OET handles invalid files
  Given the Observation Execution Tool create command
  When OET create is given a <file> that does not exist
  Then the OET returns an <error>

  Examples:
    | file                    | error                                              |
    | file:///FileNotFound.py | FileNotFoundError: No such file or directory       |
    | sdljfsdjkfhsd           | ValueError: Script URI type not handled            |

Run tests and upload results#

Run locally#

Execute tests using pytest:

pytest tests/bdd/ -v

Upload results to JIRA#

The CI/CD pipeline handles this automatically:

  1. Runs tests with pytest-bdd

  2. Outputs results to a .json file

  3. Uploads the JSON to JIRA via XRay

  4. Updates Test and Requirement ticket statuses

Warning

Only run JIRA integration on the main/master branch of integration repositories like skampi. This prevents flooding JIRA with thousands of test execution tickets.

For other repositories, view test results in the standard GitLab CI/CD pipeline output.