pytest-pagerduty 1.0.0

pytest-pagerduty

This plugin integrates PagerDuty incident management with your pytest test suite.

It automatically triggers a PagerDuty incident when a test failure occurs, allowing for real-time monitoring and faster incident response.

Installation

pip install pytest-pagerduty

Configuration

Set the required PagerDuty credentials as environment variables or provide them via pytest options:

# Use your PagerDuty API key or OAuth token either as environment variables or pytest options
export PAGERDUTY_API_KEY="your_api_key"
export PAGERDUTY_OAUTH_TOKEN="your_oauth_token"
export PAGERDUTY_DEFAULT_FROM="your_business_email@example.com"

Alternatively, use pytest command-line options:

pytest --pagerduty_api_key=your_api_key \
       --pagerduty_oauth_token=your_oauth_token \
       --pagerduty_default_from=your_business_email@example.com

You can also configure options through a pytest.ini file or section in the project configuration file:

[pytest]
pagerduty_api_key = your_api_key
pagerduty_oauth_token = your_oauth_token
pagerduty_default_from = your_business_email@example.com

Plugin registration

Ensure the plugin is registered globally by adding the following line to tests/conftest.py:

pytest_plugins = ["pytest_pagerduty.plugin"]

Usage

Marking tests for incident reporting

Use the pagerduty_fixture fixture to enable the plugin and the @pytest.mark.pagerduty_trigger_incident marker to specify tests that should trigger PagerDuty incidents on failure.

import pytest

@pytest.mark.usefixtures("pagerduty_fixture")
@pytest.mark.pagerduty_trigger_incident(service_id="XIXOOXZ", urgency="high", assignee_id="SE169QA")
def test_critical_feature():
    """Verifies the critical feature behavior."""
    assert False  # This will trigger a PagerDuty incident and assign it to the specified user who will be responsible for resolving the incident

@pytest.mark.usefixtures("pagerduty_fixture")
@pytest.mark.pagerduty_trigger_incident(service_id="XIXOOXZ", urgency="low")
def test_service_failure():
    """Validates the service availability."""
    assert False  # This will trigger a PagerDuty incident with low urgency level


@pytest.mark.usefixtures("pagerduty_fixture")
@pytest.mark.pagerduty_trigger_incident(service_id="IIXOOXZ", urgency="high")
def test_critical_flow():
    """Validates the critical flow.
    
    Critical test case which verifies next behavior:
    - Authentication to the production environment
    - Data retrieval from the X service
    - Data processing via the Y service
    - Data validation via the Z service
    - Data storage to the production database
    - Sending a notification to the Billing team
    """
    ...
    expected_status_code = 201
    actual_status_code = 502
    assert expected_status_code == actual_status_code  # This will trigger a PagerDuty incident and docstring will be included in the incident details

Marker Parameters

• service_id (required): The PagerDuty service ID.

• priority_id (optional): Incident priority reference.

• escalation_policy_id (optional): Escalation policy ID.

• urgency (optional): Incident urgency (e.g., "high" or "low").

• incident_key (optional): Deduplication key to prevent duplicate incidents.

• details (optional): Custom message for the incident body.

• assignee_id (optional): User ID to assign the incident.

PagerDuty incident structure

When a test fails, an incident is created with the following information:

• Summary: Test failure message, including the test name.

• Details: Test docstring and assertion error traceback.

• Service: Linked to the specified PagerDuty service.

• Urgency, Escalation Policy: Configurable via markers.

MIT License

Distributed under the MIT License. See LICENSE for more information.

Useful links

• python-pagerduty APIs: Clients for PagerDuty’s APIs documentation.
• python-pagerduty: GitHub repository for the python-pagerduty library.
• API Reference: PagerDuty REST API documentation.