Supported Framework

Supported Frameworks

Use this page to run your Python tests under the SeaLights agent so test execution and per-test coverage are reported to SeaLights. The agent wraps your existing test framework — no test code changes are required.

This page covers the three frameworks most teams integrate in 2026: pytest, unittest, and behave.

If you are looking for how to instrument the Application Under Test (AUT) so it reports coverage at runtime (e.g., Flask, FastAPI, Django, uWSGI, Gunicorn), see Running Backend Server Using SeaLights Agent. For functional / integration / E2E tests, you will use both pages.

How the Python agent fits in

The Python agent plays one of two roles depending on the test type, mapping to the two SeaLights Agent Usage Modes:

Scenario	What you instrument	Coverage source	Test execution source
Unit / in-process tests	The test framework (this page)	The test process itself	The test process itself
Functional / integration / E2E	The test framework (this page) and the AUT (backend-server page)	The running AUT	The test framework

In SeaLights terminology, sl-python <framework> runs the Python agent in Test Runner Mode. For functional tests, the AUT runs separately in Coverage Listener Mode, and the two share a Lab ID so SeaLights can correlate test events with coverage footprints.

---

Prerequisites

Before running the commands below, ensure you have:

1. An agent token. See Generating an Agent Token. Treat the token as a secret — the snippets on this page read it from a SL_TOKEN environment variable rather than checking it in.
2. A Lab ID for the environment under test. Lab IDs are how SeaLights groups a test run with the build under test. The snippets read it from a SL_LABID environment variable so the same pipeline can target multiple environments.
3. A scanned build for the code under test. See Scanning a Build.
4. The agent installed in the Python environment that runs your tests: pip install sealights-python-agent.
5. For functional / integration / E2E tests only: the AUT is already running and instrumented. See Running Backend Server Using SeaLights Agent.

Per-framework usage

Frameworks are listed in order of common usage in 2026. New integrations should default to pytest unless an existing test suite dictates otherwise.

Legacy frameworks (unittest2, nose). sl-python retains subcommands for unit2 (unittest2) and nose for backward compatibility. Both upstream projects are no longer actively maintained, and we recommend migrating to pytest or unittest. For exact usage of the legacy subcommands, run sl-python --help or sl-python <unit2|nose> --help.

pytest

The de facto standard for Python testing. Use for unit tests, API tests, and most automated test suites.

The SeaLights agent conflicts with pytest's --cov option. Remove --cov from your command line and from any pytest.ini / pyproject.toml / setup.cfg when running under sl-python.

If pytest-cov is in your project at a version older than the one sl-python requires, coverage collection will fail. Remove pytest-cov from your dependencies — sl-python installs a compatible version automatically.

Bash

export SL_TOKEN="<your-sealights-agent-token>"
export SL_LABID="my_app_env"

sl-python pytest \
  --token "$SL_TOKEN" \
  --labId "$SL_LABID" \
  --testStage "Unit Tests" \
  --cov-report ./reports/coverage.xml \
  tests/

GitHub Actions

- name: Run pytest with SeaLights
  shell: bash
  env:
    SL_TOKEN: ${{ secrets.SEALIGHTS_AGENT_TOKEN }}
    SL_LABID: ${{ vars.SEALIGHTS_LAB_ID }}
  run: |
    pip install sealights-python-agent
    sl-python pytest \
      --token "$SL_TOKEN" \
      --labId "$SL_LABID" \
      --testStage "Unit Tests" \
      --cov-report ./reports/coverage.xml \
      tests/

PowerShell

$env:SL_TOKEN = "<your-sealights-agent-token>"
$env:SL_LABID = "my_app_env"

sl-python pytest `
  --token $env:SL_TOKEN `
  --labId $env:SL_LABID `
  --testStage "Unit Tests" `
  --cov-report .\reports\coverage.xml `
  tests\

unittest

Python's built-in testing framework. Use when stdlib-only constraints apply, or for legacy suites not yet migrated to pytest.

Bash

export SL_TOKEN="<your-sealights-agent-token>"
export SL_LABID="my_app_env"

sl-python unittest \
  --token "$SL_TOKEN" \
  --labId "$SL_LABID" \
  --testStage "Unit Tests" \
  --cov-report ./reports/coverage.xml \
  discover -s tests

GitHub Actions

- name: Run unittest with SeaLights
  shell: bash
  env:
    SL_TOKEN: ${{ secrets.SEALIGHTS_AGENT_TOKEN }}
    SL_LABID: ${{ vars.SEALIGHTS_LAB_ID }}
  run: |
    pip install sealights-python-agent
    sl-python unittest \
      --token "$SL_TOKEN" \
      --labId "$SL_LABID" \
      --testStage "Unit Tests" \
      --cov-report ./reports/coverage.xml \
      discover -s tests

PowerShell

$env:SL_TOKEN = "<your-sealights-agent-token>"
$env:SL_LABID = "my_app_env"

sl-python unittest `
  --token $env:SL_TOKEN `
  --labId $env:SL_LABID `
  --testStage "Unit Tests" `
  --cov-report .\reports\coverage.xml `
  discover -s tests

behave

BDD framework for Python, used for functional and acceptance tests written in Gherkin and typically paired with a separately instrumented AUT.

For Behave, the AUT is almost always a separate running service. Make sure it is already instrumented per the backend-server page, and that both sides use the same --labId.

Bash

export SL_TOKEN="<your-sealights-agent-token>"
export SL_LABID="my_app_env"

sl-python behave \
  --token "$SL_TOKEN" \
  --labId "$SL_LABID" \
  --testStage "Functional Tests" \
  features/

GitHub Actions

- name: Run Behave with SeaLights
  shell: bash
  env:
    SL_TOKEN: ${{ secrets.SEALIGHTS_AGENT_TOKEN }}
    SL_LABID: ${{ vars.SEALIGHTS_LAB_ID }}
  run: |
    pip install sealights-python-agent
    sl-python behave \
      --token "$SL_TOKEN" \
      --labId "$SL_LABID" \
      --testStage "Functional Tests" \
      features/

PowerShell

$env:SL_TOKEN = "<your-sealights-agent-token>"
$env:SL_LABID = "my_app_env"

sl-python behave `
  --token $env:SL_TOKEN `
  --labId $env:SL_LABID `
  --testStage "Functional Tests" `
  features\

---

Common parameters

All sl-python <framework> subcommands accept the following parameters unless noted otherwise.

Deprecated: --buildSessionId and --buildSessionIdFile are deprecated in favor of --labId. They still work for backward compatibility, but new integrations should use --labId.

Parameter	Type	Description
--token	string	SeaLights agent token. Mandatory unless --tokenfile is used. Case-sensitive.
--tokenFile	path	Path to a file containing the token. Case-sensitive.
--labId	string	Lab ID for the target environment. Case-sensitive.
--testStage	string	Human-readable name of the test stage, e.g. Unit Tests, Integration Tests, Regression. Appears in the SeaLights UI.
--cov-report	path	Path where the agent writes the coverage XML report.
--per-test	boolean	Capture per-test coverage. Default: true (pytest, unittest).
--interval	int (ms)	Footprint flush interval. Default: 10000 (pytest).
--disableTia, -tsd	flag	Disable Test Optimization for this run (pytest).
--test-selection-retry-interval, -tsri	int (sec)	Retry interval when fetching the exclusion list. Default: 5 (pytest).
--test-selection-retry-timeout, -tsrt	int (sec)	Total timeout for fetching the exclusion list. Default: 60 (pytest).

Troubleshooting

tests must run for at least 1 second for SeaLights to calculate coverage SeaLights samples footprints periodically. If a test process completes in under one second, the sampler may not capture anything. For very fast unit-test suites, add a short delay at the end of the run, or batch tests so total wall time exceeds one second.

token is required / authentication errors Verify the SL_TOKEN environment variable is set in the shell that runs sl-python, and that it resolves to a valid, non-expired token. In CI, confirm the secret is bound to the job (e.g. that the env: block at job/step scope references the right secret name).

No coverage appears in SeaLights for functional tests The Lab ID on sl-python <framework> must match the Lab ID configured on the running AUT. If they don't match, test events and coverage footprints land in different buckets and cannot be correlated. Verify both sides are using the same --labId.

pytest-cov version conflict If pytest-cov is in your project's dependency lock at a version older than sl-python requires, the agent fails to attach. Remove pytest-cov from your project's direct dependencies — sl-python installs a compatible version itself.

Conflicting coverage flags on pytest Remove --cov from your test command and from any config file (pytest.ini, pyproject.toml, setup.cfg). The SeaLights agent provides its own coverage collection and cannot share the process with another collector.

Tests run but no test stage opens in SeaLights. Check that --testStage is provided and that the agent has network access to the SeaLights server. Enable agent logs to confirm the test session lifecycle messages.