{"id":4342,"library":"buildkite-test-collector","title":"Buildkite Test Collector for Python","description":"The `buildkite-test-collector` is the official Python adapter for Buildkite Test Engine, designed to collect and report test results, primarily from `pytest` suites, to the Buildkite Test Engine dashboard. It integrates seamlessly with CI environments and is actively maintained with frequent updates.","status":"active","version":"1.4.1","language":"en","source_language":"en","source_url":"https://github.com/buildkite/test-collector-python","tags":["buildkite","ci","testing","pytest","test-engine","analytics"],"install":[{"cmd":"pip install buildkite-test-collector","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"The collector primarily functions as a pytest plugin to gather test results and requires pytest to run tests.","package":"pytest","optional":false}],"imports":[{"note":"Functionality is automatically enabled when `buildkite-test-collector` is installed alongside `pytest`.","symbol":"pytest_plugin","correct":"The library acts as a pytest plugin; no explicit import is typically required for basic functionality."}],"quickstart":{"code":"import os\n\n# test_example.py\ndef test_passing_example():\n    assert True\n\ndef test_failing_example():\n    assert False\n\n# To run:\n# 1. Set the Buildkite Analytics Token:\n#    export BUILDKITE_ANALYTICS_TOKEN='your-api-token'\n# 2. Run pytest:\n#    pytest\n# You can use os.environ.get('BUILDKITE_ANALYTICS_TOKEN', '') for local testing\n# but in CI, it must be properly set as an environment variable.","lang":"python","description":"To quickly start collecting test data, first install the library and pytest. Then, set the `BUILDKITE_ANALYTICS_TOKEN` environment variable with your Buildkite Test Engine API token and run your pytest suite as usual. The collector will automatically send test results to Buildkite. For local testing, ensure `BUILDKITE_ANALYTICS_TOKEN` is set, or mock it."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer.","message":"Python 3.8 is no longer supported. The library now requires Python >= 3.9.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"For common CI systems, upgrade to v1.3.1 or later. For unknown CI systems or older versions, ensure the `CI` environment variable is set to any value, e.g., `CI=true`.","message":"The requirement for the `CI` environment variable for uploads has changed multiple times. While v1.3.1 introduced automatic detection for common CI systems (Buildkite, GitHub Actions, CircleCI), older versions or less common CI systems might still require it.","severity":"gotcha","affected_versions":"<1.3.1"},{"fix":"Upgrade to v1.3.0 or later to ensure teardown failures are correctly reported.","message":"Teardown failures were previously ignored and not reported as failed tests. This was fixed in v1.3.0.","severity":"breaking","affected_versions":"<1.3.0"},{"fix":"Upgrade to v1.4.0 or later to ensure correct reporting of subtest results without overwriting the parent test's outcome.","message":"Subtest reports in pytest might have incorrectly overwritten the parent test result in versions prior to v1.4.0.","severity":"gotcha","affected_versions":"<1.4.0"},{"fix":"Always set the `BUILDKITE_ANALYTICS_TOKEN` securely in your CI environment or locally during development.","message":"The `BUILDKITE_ANALYTICS_TOKEN` environment variable is mandatory for the collector to upload test results. Without it, tests will run but results won't be sent to Buildkite.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the Buildkite documentation for the correct `span detail` format and update any custom tracing implementations.","message":"The format for `span detail` objects in tracing was fixed in v1.2.0 to align with Buildkite's documentation. If you were manually crafting span data, its format might need adjustment.","severity":"breaking","affected_versions":"<1.2.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}