Getting Started with pytest-bdd-ewx

Welcome to pytest-bdd-ewx ! This framework extends the power of PyTest BDD plugin to provide the capabilities to create test scenarios for the Energyworx platform.

🏗 Create a test project

To begin, create your test project with the following structure:

|-  my-test-project
    |-  my_test_scenarios
    ...
    |-  resources

my_test_scenarios will contain the actual tests, it can be also multiple folders containing tests for different use cases
resources folder will contain some test data, please see more information below

Create a virtual environment and install pytest-bdd-ewx and ewx-cli as described on the pytest-bdd-ewx installation page, pinned to the version matching your platform release (see Versioning).

The plugin loads automatically

pytest-bdd-ewx registers itself with pytest through the pytest11 entry point, so pytest picks it up as soon as it is installed in the active environment. You only need PYTEST_PLUGINS=pytest_bdd_ewx.plugin (or pytest_plugins = ["pytest_bdd_ewx.plugin"] in a root conftest.py) when plugin autoloading is disabled in your setup, for example with PYTEST_DISABLE_PLUGIN_AUTOLOAD=1.

Now you can start writing your tests using the Gherkin syntax (if you are unfamiliar with it, please refer to the documentation for more details about the syntax).

📂 Add test files

Create a .feature file containing one or multiple scenarios that you want to test. For convenience, a dedicated features folder can be created. To execute the test, you will need to create a pytest .py file with the scenario-decorated functions. See example:

|-  my-test-project
    |-  my_test_scenarios
        |-  features
            |-  test_ingestion.feature
            ...
        |-  test_ingestion.py
        ...

Feature file will have a Feature described and a Scenario written in Gherkin syntax utilising the steps defined in pytest-bdd-ewx plugin.

For more information, please refer to Using the plugin

🛠️ Create a simple test

Example: test_ingestion.feature

Feature: File ingestion
    As a QA engineer
    I want to ingest the file
    In order created a datasource

    Scenario: The datasource is created via file ingestion
        Given I upload the file "test_data.csv"
        When I ingest the file "test_data.csv" with market adapter "csv_market_adapter"
        Then there is a datasource with id "TEST_DATASOURCE"

Corresponding test_ingestion.py file:

from pytest_bdd import scenario


@scenario("features/test_ingestion.feature", "The datasource is created via file ingestion")
def test_ingestion():
    pass

This way, pytest-bdd-ewx will seamlessly integrate with pytest to discover and execute your BDD tests.

💡 For more information about available steps in the plugin, please refer to Available Gherkin Steps documentation.

📜 Add test data

We distinguish 2 types of test resources management:

Test data management: please note the test_data.csv file location in the resources folder. The folder structure should be exactly as the following, otherwise the plugin will not be able to find it:

|-  my-test-project
    |-  my_test_scenarios
        |-  features
            ...
        |-  resources
            |-  test-data
                |-  files
                    |-  test_data.csv
                    |-  another_test_data.json
                    ...

The resources folder is also used for some more advanced scenarios test data, see Using the plugin for more information.

Test configurations management: in case your market adapter or some other configurations for your test (like flows, rules, etc.) are not present on the target namespace, it is possible to create those as a precondition to your test scenarios. For seamless configuration management, we recommend utilising ewx-cli energyworx tool which helps with both downloading and uploading the needed configurations for the specific test case. Please refer to the last section in Using the plugin on how to set it up.

Supposing you have your test configurations on the target namespace, you can execute your tests.

🚀 Start testing

Now you can start your test by the following command:

pytest my_test_scenarios/test_ingestion.py

To have more logging information regarding the tests execution, you can run the following command:

pytest --log-cli-level=INFO my_test_scenarios/test_ingestion.py -x

When the test is started, you will be suggested to specify an environment and a target namespace to run the tests. Follow the instructions in order to authenticate your user to the platform (normally you will need to do it only once after you start testing on a new environment).

It is also possible to create your own custom step definitions, if needed. For more information on how to create the tests and utilise the plugin, please refer to the Using the plugin

⚙️ Running non-interactively (environment variables and CI)

Without any configuration the plugin prompts for the environment and namespace on the first run and then reuses the credentials that ewx-cli stored for that project. For repeatable local runs, and always in CI, set these variables instead:

Variable	Example	Description
`AUTOMATED_TESTS_ENVIRONMENT`	`company-prd`	Project prefix of the environment, the part of the console URL before `.energyworx.net`
`AUTOMATED_TESTS_NAMESPACE_ID`	`enrx_org_001`	Namespace all API calls are made in. Required when the environment is set
`AUTOMATED_TESTS_APIV2_ID`		Client ID of a client-credentials pair
`AUTOMATED_TESTS_APIV2_KEY`		Client secret of that pair
`URL_BASE_PROJECT_ID`	`company-prd-eu`	Optional. Only when the API host differs from the project prefix

The client credentials are the same ones used for any automated API access: create a pair under Settings → Automated access in the console and bind it to a service account with the permissions your scenarios need, as described in Automated API Access. When the two APIV2 variables are not set, the plugin falls back to the credentials ewx-cli stored interactively.

A minimal GitLab CI job that runs a suite nightly against an acceptance namespace looks like this, with the client credentials stored as masked CI variables:

.gitlab-ci.yml
system-tests:
  image: python:3.13-slim
  variables:
    AUTOMATED_TESTS_ENVIRONMENT: company-acc
    AUTOMATED_TESTS_NAMESPACE_ID: enrx_org_002
    # AUTOMATED_TESTS_APIV2_ID and AUTOMATED_TESTS_APIV2_KEY are masked CI/CD variables
  before_script:
    - pip install keyring keyrings.google-artifactregistry-auth
    - pip install --index-url https://europe-west1-python.pkg.dev/ewx-global/python-shared/simple/
        --extra-index-url https://pypi.org/simple/ ewx-cli pytest-bdd-ewx
  script:
    - pytest --log-cli-level=INFO my_test_scenarios/
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

Installing from the Energyworx registry in CI needs a Google identity with access to it; the simplest is gcloud auth activate-service-account with a service-account key stored as a CI variable before the pip install lines, or a runner that already carries Google credentials.

Switching API versions

Steps talk to API v1.5 by default. Scenarios that exercise API v2 endpoints switch with:

Given I switch to api version "2"

Both versions authenticate with the same client credentials. See Plugin features for how the plugin supports multiple APIs.

🏗 Create a test project​

📂 Add test files​

🛠️ Create a simple test​

📜 Add test data​

🚀 Start testing​

⚙️ Running non-interactively (environment variables and CI)​

Switching API versions​