Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

6.7 KB
Raw Blame
from typing import Optional, cast

from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    detect,
)
from products.warehouse_sources.sources.testrail._config import TestrailSourceConfig
from products.warehouse_sources.sources.testrail.settings import ENDPOINTS, INCREMENTAL_FIELDS, TESTRAIL_ENDPOINTS
from products.warehouse_sources.sources.testrail.testrail import (
    TestrailResumeConfig,
    testrail_source,
    validate_credentials as validate_testrail_credentials,
)


@SourceRegistry.register
class TestrailSource(ResumableSource[TestrailSourceConfig, TestrailResumeConfig]):
    codebase_detection = detect(env=("^TESTRAIL_",), pypi=("trcli",))

    lists_tables_without_credentials = True  # static endpoint catalog — safe for public docs
    supported_versions = ("v2",)
    default_version = "v2"
    api_docs_url = "https://support.testrail.com/hc/en-us/articles/7077083596436-Introduction-to-the-TestRail-API"

    @property
    def source_type(self) -> ExternalDataSourceType:
        return ExternalDataSourceType.TESTRAIL

    @property
    def connection_host_fields(self) -> list[str]:
        # The API key is sent to `<subdomain>.testrail.io`, so changing the subdomain must
        # re-require the key.
        return ["subdomain"]

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.TESTRAIL,
            category=DataWarehouseSourceCategory.ENGINEERING___MONITORING,
            label="TestRail",
            releaseStatus=ReleaseStatus.BETA,
            caption="""Enter your TestRail Cloud address, email, and API key to pull your test management data into the PostHog Data warehouse.

Generate an API key under **My Settings → API keys** in TestRail, and make sure the API is enabled for your instance under **Administration → Site Settings → API**. Self-hosted TestRail Server instances on custom domains are not supported yet.""",
            iconPath="/static/services/testrail.png",
            docsUrl="https://posthog.com/docs/cdp/sources/testrail",
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="subdomain",
                        label="TestRail address",
                        type=SourceFieldInputConfigType.TEXT,
                        required=True,
                        placeholder="yourcompany",
                        secret=False,
                    ),
                    SourceFieldInputConfig(
                        name="username",
                        label="Email",
                        type=SourceFieldInputConfigType.EMAIL,
                        required=True,
                        placeholder="[email protected]",
                        secret=False,
                    ),
                    SourceFieldInputConfig(
                        name="api_key",
                        label="API key",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                ],
            ),
        )

    def get_canonical_descriptions(self) -> CanonicalDescriptions:
        from products.warehouse_sources.sources.testrail.canonical_descriptions import (
            CANONICAL_DESCRIPTIONS,  # noqa: PLC0415
        )

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            # 401/403 surface as a requests HTTPError when `_fetch` calls `raise_for_status()`.
            # Retrying can never fix a credential/permission problem, so fail the sync.
            "401 Client Error: Unauthorized": "Your TestRail email or API key is invalid or has been revoked. Generate a new key under My Settings → API keys, then reconnect.",
            "403 Client Error: Forbidden": "TestRail rejected the request. Check that the API is enabled (Administration → Site Settings → API) and that your account can read this data, then reconnect.",
        }

    def get_schemas(
        self,
        config: TestrailSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        schemas = [
            SourceSchema(
                name=endpoint,
                supports_incremental=endpoint_config.incremental_param is not None,
                supports_append=endpoint_config.incremental_param is not None,
                incremental_fields=INCREMENTAL_FIELDS.get(endpoint, []),
            )
            for endpoint, endpoint_config in TESTRAIL_ENDPOINTS.items()
        ]
        if names is not None:
            names_set = set(names)
            schemas = [s for s in schemas if s.name in names_set]
        return schemas

    def validate_credentials(
        self,
        config: TestrailSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        # TestRail access is account-wide (project permissions surface per request at sync
        # time), so a single get_projects probe validates the credentials for every schema.
        return validate_testrail_credentials(config.subdomain, config.username, config.api_key)

    def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[TestrailResumeConfig]:
        return ResumableSourceManager[TestrailResumeConfig](inputs, TestrailResumeConfig)

    def source_for_pipeline(
        self,
        config: TestrailSourceConfig,
        resumable_source_manager: ResumableSourceManager[TestrailResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        if inputs.schema_name not in ENDPOINTS:
            raise ValueError(f"Unknown TestRail schema '{inputs.schema_name}'")

        return testrail_source(
            subdomain=config.subdomain,
            username=config.username,
            api_key=config.api_key,
            endpoint=inputs.schema_name,
            logger=inputs.logger,
            resumable_source_manager=resumable_source_manager,
            should_use_incremental_field=inputs.should_use_incremental_field,
            db_incremental_field_last_value=inputs.db_incremental_field_last_value
            if inputs.should_use_incremental_field
            else None,
        )