@bugbug-io/sdk
    Preparing search index...

    Class TestsModule

    Tests module — manage BugBug tests and their runs.

    Exposes CRUD over /tests/, run lifecycle over /testruns/, component linking, debug artifacts, and YAML/ZIP export/import. Use startRun for the recommended high-level entry point with optional progress watching.

    Index

    Constructors

    constructor

    Methods

    list getAll get create update partialUpdate delete linkComponent unlinkComponent startRun getRun getRunProgress stopRun getRunScreenshots listRuns updateStepPosition getRecentRuns downloadRunJunitReport getRunLogs watchRunProgress listRunDebugArtifacts getRunDebugArtifact export import

    Constructors

    • Parameters

      • client: BugBugApiClient

      Returns TestsModule

    Methods

    • List tests with pagination, search, and ordering.

      Parameters

      • options: ListTestsOptions = {}
        • Optionalcursor?: string
        • OptionalpageSize?: number
        • Optionalquery?: string
        • Optionalordering?: "-created" | "-name" | "created" | "name"
        • OptionallatestRun?: boolean
        • Optionalsignal?: AbortSignal

          Abort signal for client-side cancellation. Throws CancellationError.

        • Optionaltimeout?: number

          Per-request timeout in milliseconds. Overrides BugBugConfig.timeout for this call only.

        • Optionalheaders?: Record<string, string>

          Per-request HTTP headers. These are merged first so the SDK's auth and User-Agent headers always win — supplying Authorization here will have no effect.

      Returns Promise<TestsListResponse>

      Paginated TestsListResponse envelope (validated via Zod).

      When the server response fails Zod validation.

    • Fetch a single test by ID.

      Parameters

      Returns Promise<Test>

      The full Test resource.

      When no test matches testId.

    • Create a new empty test.

      Parameters

      • data: {
            name?: string | null;
            screenSizeType?: "desktop" | "mobile" | "custom";
            notes?: string | null;
            folderId?: string | null;
        }

        Test creation payload (at minimum, name and screenSizeType).

        • Optionalname?: string | null
        • OptionalscreenSizeType?: "desktop" | "mobile" | "custom"
          • desktop - Desktop
            • mobile - Mobile
            • custom - Custom
        • Optionalnotes?: string | null

          Test notes

        • OptionalfolderId?: string | null

          Format: uuid

      • options: RequestOptions = {}

      Returns Promise<Test>

      The newly-created Test.

      On invalid payload (DRF field errors on error.fields).

    • Update a test. The tests endpoint accepts partial payloads via PATCH, so this and partialUpdate share the same semantics.

      Parameters

      • testId: string

        UUID of the test to update.

      • data: {
            name?: string | null;
            screenSizeType?: "desktop" | "mobile" | "custom";
            notes?: string | null;
            folderId?: string | null;
        }

        Fields to patch.

        • Optionalname?: string | null
        • OptionalscreenSizeType?: "desktop" | "mobile" | "custom"
          • desktop - Desktop
            • mobile - Mobile
            • custom - Custom
        • Optionalnotes?: string | null

          Test notes

        • OptionalfolderId?: string | null

          Format: uuid

      • options: RequestOptions = {}

      Returns Promise<Test>

      When the test does not exist.

      When the payload fails server-side validation.

    • Alias for update. The tests endpoint already uses PATCH semantics.

      Parameters

      • testId: string
      • data: {
            name?: string | null;
            screenSizeType?: "desktop" | "mobile" | "custom";
            notes?: string | null;
            folderId?: string | null;
        }
        • Optionalname?: string | null
        • OptionalscreenSizeType?: "desktop" | "mobile" | "custom"
          • desktop - Desktop
            • mobile - Mobile
            • custom - Custom
        • Optionalnotes?: string | null

          Test notes

        • OptionalfolderId?: string | null

          Format: uuid

      • options: RequestOptions = {}

      Returns Promise<Test>

    • Delete a test by ID.

      Parameters

      Returns Promise<void>

      When the test does not exist.

    • Link an existing component/group into a test at an optional position.

      Parameters

      • testId: string

        UUID of the test to insert into.

      • data: { groupId?: string; componentId?: string; atIndex?: number | null }

        { groupId, atIndex? } insertion descriptor.

        • OptionalgroupId?: string

          Format: uuid

        • OptionalcomponentId?: string

          Format: uuid

        • OptionalatIndex?: number | null
      • options: RequestOptions = {}

      Returns Promise<Test>

      Insert response with the resulting step layout.

    • Unlink a component/group from a test.

      Parameters

      • testId: string

        UUID of the test to unlink from.

      • data: { groupId: string }

        Unlink descriptor identifying which component to remove.

        • groupId: string

          Format: uuid

      • options: RequestOptions = {}

      Returns Promise<Test>

    • Start a test run by name or ID, optionally watching progress until completion.

      When testNameOrId is a UUID the test is run directly. Otherwise it is looked up by name first (NotFoundError on miss). When watchProgress is true, the call polls until the run reaches a terminal status and returns the full TestRun; otherwise it returns the initial TestRunState synchronously after enqueueing the run.

      Parameters

      • testNameOrId: string

        Test UUID or human-readable test name.

      • options: RunTestWatchProgressOptions
        • OptionalprofileName?: string
        • Optionalvariables?: { key: string; value?: string | null }[]
        • watchProgress: true
        • OptionalpollInterval?: number
        • Optionaltimeout?: number

          Per-request timeout in milliseconds. Overrides BugBugConfig.timeout for this call only.

        • OptionalonProgress?: (
              status: {
                  id: string;
                  finishedSteps: number;
                  modified: string;
                  status:
                      | "error"
                      | "passed"
                      | "failed"
                      | "running"
                      | "auto_retrying"
                      | "stopped"
                      | "queued"
                      | "paused"
                      | "skipped"
                      | "recording"
                      | "initialized";
                  totalSteps: number;
                  webappUrl: string;
                  duration: string
                  | null;
              },
          ) => void
          | Promise<void>
        • Optionalsignal?: AbortSignal

          Abort signal for client-side cancellation. Throws CancellationError.

        • Optionalheaders?: Record<string, string>

          Per-request HTTP headers. These are merged first so the SDK's auth and User-Agent headers always win — supplying Authorization here will have no effect.

      Returns Promise<
          {
              browserName: string
              | null;
              browserVersion: string | null;
              browserHeight: number | null;
              browserWidth: number | null;
              stepsRuns: string;
              userId: string | null;
              duration: string | null;
              ended: string | null;
              errorCode: string | null;
              extensionVersion: string | null;
              id: string;
              isAutoRetried: boolean;
              name: string;
              osName: string | null;
              profileId: string;
              profileName: string;
              queued: string | null;
              runMode: "recording" | "server" | "local";
              runProfileId: string | null;
              screenSizeType: "desktop" | "mobile" | "custom";
              section: "main" | "before_all" | "after_all";
              sequence: number | null;
              started: string | null;
              status:
                  | "error"
                  | "passed"
                  | "failed"
                  | "running"
                  | "auto_retrying"
                  | "stopped"
                  | "queued"
                  | "paused"
                  | "skipped"
                  | "recording"
                  | "initialized";
              suiteRunId: string
              | null;
              testId: string | null;
              triggeredBy:
                  | "user"
                  | "api"
                  | "webhook"
                  | "scheduler"
                  | "github"
                  | "cli"
                  | "agent";
              webappUrl: string;
          },
      >

      When testNameOrId is not a UUID and no test matches that name.

      When watchProgress is true and the run does not finish in time.

      // Fire-and-forget run by name
      const status = await sdk.tests.startRun('Smoke / login');

      // Run by ID, watch progress for up to 10 minutes
      const run = await sdk.tests.startRun('11111111-1111-4111-8111-111111111111', {
        watchProgress: true,
        timeout: 600_000,
        profileName: 'Production',
        onProgress: (s) => console.log(`${s.id}: ${s.status} (${s.finishedSteps}/${s.totalSteps})`),
      });

    • Start a test run by name or ID, optionally watching progress until completion.

      When testNameOrId is a UUID the test is run directly. Otherwise it is looked up by name first (NotFoundError on miss). When watchProgress is true, the call polls until the run reaches a terminal status and returns the full TestRun; otherwise it returns the initial TestRunState synchronously after enqueueing the run.

      Parameters

      • testNameOrId: string

        Test UUID or human-readable test name.

      • Optionaloptions: RunTestNoWatchProgressOptions
        • OptionalprofileName?: string
        • Optionalvariables?: { key: string; value?: string | null }[]
        • OptionalwatchProgress?: false
        • Optionalsignal?: AbortSignal

          Abort signal for client-side cancellation. Throws CancellationError.

        • Optionaltimeout?: number

          Per-request timeout in milliseconds. Overrides BugBugConfig.timeout for this call only.

        • Optionalheaders?: Record<string, string>

          Per-request HTTP headers. These are merged first so the SDK's auth and User-Agent headers always win — supplying Authorization here will have no effect.

      Returns Promise<
          {
              id: string;
              finishedSteps: number;
              modified: string;
              status: | "error"
              | "passed"
              | "failed"
              | "running"
              | "auto_retrying"
              | "stopped"
              | "queued"
              | "paused"
              | "skipped"
              | "recording"
              | "initialized";
              totalSteps: number;
              webappUrl: string;
              duration: string
              | null;
          },
      >

      When testNameOrId is not a UUID and no test matches that name.

      When watchProgress is true and the run does not finish in time.

      // Fire-and-forget run by name
      const status = await sdk.tests.startRun('Smoke / login');

      // Run by ID, watch progress for up to 10 minutes
      const run = await sdk.tests.startRun('11111111-1111-4111-8111-111111111111', {
        watchProgress: true,
        timeout: 600_000,
        profileName: 'Production',
        onProgress: (s) => console.log(`${s.id}: ${s.status} (${s.finishedSteps}/${s.totalSteps})`),
      });

    • Fetch full test-run details including step runs.

      Parameters

      Returns Promise<
          {
              browserName: string
              | null;
              browserVersion: string | null;
              browserHeight: number | null;
              browserWidth: number | null;
              stepsRuns: string;
              userId: string | null;
              duration: string | null;
              ended: string | null;
              errorCode: string | null;
              extensionVersion: string | null;
              id: string;
              isAutoRetried: boolean;
              name: string;
              osName: string | null;
              profileId: string;
              profileName: string;
              queued: string | null;
              runMode: "recording" | "server" | "local";
              runProfileId: string | null;
              screenSizeType: "desktop" | "mobile" | "custom";
              section: "main" | "before_all" | "after_all";
              sequence: number | null;
              started: string | null;
              status:
                  | "error"
                  | "passed"
                  | "failed"
                  | "running"
                  | "auto_retrying"
                  | "stopped"
                  | "queued"
                  | "paused"
                  | "skipped"
                  | "recording"
                  | "initialized";
              suiteRunId: string
              | null;
              testId: string | null;
              triggeredBy:
                  | "user"
                  | "api"
                  | "webhook"
                  | "scheduler"
                  | "github"
                  | "cli"
                  | "agent";
              webappUrl: string;
          },
      >

      When the run does not exist.

    • Fetch only the lightweight status of a test run (no step detail). Prefer this over getRun when polling.

      Parameters

      Returns Promise<
          {
              id: string;
              finishedSteps: number;
              modified: string;
              status: | "error"
              | "passed"
              | "failed"
              | "running"
              | "auto_retrying"
              | "stopped"
              | "queued"
              | "paused"
              | "skipped"
              | "recording"
              | "initialized";
              totalSteps: number;
              webappUrl: string;
              duration: string
              | null;
          },
      >

    • Request cancellation of an in-progress test run.

      Parameters

      Returns Promise<
          {
              id: string;
              finishedSteps: number;
              modified: string;
              status: | "error"
              | "passed"
              | "failed"
              | "running"
              | "auto_retrying"
              | "stopped"
              | "queued"
              | "paused"
              | "skipped"
              | "recording"
              | "initialized";
              totalSteps: number;
              webappUrl: string;
              duration: string
              | null;
          },
      >

      The updated status; the run may still take a moment to settle.

    • Fetch step-level screenshots captured during a run.

      Parameters

      Returns Promise<{ id: string; stepId: string | null; screenshotUrl: string }[]>

      Per-step-run screenshot entries; empty array when none available.

    • List test runs filtered by status, time window, and optional test ID.

      Parameters

      • options: ListTestRunsOptions = {}
        • Optionalcursor?: string
        • OptionalpageSize?: number
        • Optionalordering?: "-created" | "created" | "-started" | "started"
        • OptionalstartedAfter?: string
        • OptionalstartedBefore?: string
        • Optionalstatus?:
              | "error"
              | "passed"
              | "failed"
              | "running"
              | "auto_retrying"
              | "stopped"
              | "queued"
              | "paused"
              | "skipped"
              | "recording"
              | "initialized"
        • OptionaltestId?: string
        • Optionalsignal?: AbortSignal

          Abort signal for client-side cancellation. Throws CancellationError.

        • Optionaltimeout?: number

          Per-request timeout in milliseconds. Overrides BugBugConfig.timeout for this call only.

        • Optionalheaders?: Record<string, string>

          Per-request HTTP headers. These are merged first so the SDK's auth and User-Agent headers always win — supplying Authorization here will have no effect.

      Returns Promise<TestRunsListResponse>

      Paginated TestRunsListResponse.

    • Move a step to a new position within a test's step list.

      Parameters

      • testId: string

        UUID of the test to reorder.

      • data: { stepId: string; groupId?: string; atIndex?: number; blockId?: string | null }

        { stepId, atIndex } move descriptor.

        • stepId: string

          Format: uuid

        • OptionalgroupId?: string

          Format: uuid

        • OptionalatIndex?: number
        • OptionalblockId?: string | null

          Format: uuid

      • options: RequestOptions = {}

      Returns Promise<void>

      The updated Test with the new step ordering.

    • Convenience wrapper around listRuns that returns runs started in the last N hours, newest first by default.

      Parameters

      • options: { hours?: number; pageSize?: number; ordering?: "-started" | "started" } & RequestOptions = {}
        • Optionalhours?: number

          Look-back window in hours (default 24).

        • OptionalpageSize?: number

          Max runs per page (default 50).

        • Optionalordering?: "-started" | "started"

          Sort order; defaults to most-recent first.

      Returns Promise<TestRunsListResponse>

    • Download the JUnit XML report for a test run. Useful for CI integrations that consume JUnit (e.g. Jenkins, GitLab CI, GitHub Actions test reporters).

      Parameters

      Returns Promise<string>

      The JUnit report body as a string.

    • Fetch test-run log output. The server may return either log content inline or a redirect/URL string — both are returned verbatim as text.

      Parameters

      Returns Promise<string>

    • Poll a test run's lightweight /status/ endpoint until it reaches a terminal status.

      Transient network errors are retried; non-network errors propagate.

      Parameters

      • runId: string

        UUID of the test run to watch.

      • onProgress: (
            status: {
                id: string;
                finishedSteps: number;
                modified: string;
                status:
                    | "error"
                    | "passed"
                    | "failed"
                    | "running"
                    | "auto_retrying"
                    | "stopped"
                    | "queued"
                    | "paused"
                    | "skipped"
                    | "recording"
                    | "initialized";
                totalSteps: number;
                webappUrl: string;
                duration: string
                | null;
            },
        ) => void
        | Promise<void>

        Invoked on every successful poll with the latest TestRunState (including the terminal one). Receives finishedSteps/totalSteps/webappUrl for in-flight progress UI.

      • options: { pollInterval?: number; timeout?: number } & RequestOptions = {}
        • OptionalpollInterval?: number

          Poll interval in ms (default 2000).

        • Optionaltimeout?: number

          Wait timeout in ms (default 300_000 = 5 minutes).

        • Optionalsignal?: AbortSignal

          Abort signal for client-side cancellation. Throws CancellationError.

        • Optionaltimeout?: number

          Per-request timeout in milliseconds. Overrides BugBugConfig.timeout for this call only.

        • Optionalheaders?: Record<string, string>

          Per-request HTTP headers. These are merged first so the SDK's auth and User-Agent headers always win — supplying Authorization here will have no effect.

      Returns Promise<
          {
              browserName: string
              | null;
              browserVersion: string | null;
              browserHeight: number | null;
              browserWidth: number | null;
              stepsRuns: string;
              userId: string | null;
              duration: string | null;
              ended: string | null;
              errorCode: string | null;
              extensionVersion: string | null;
              id: string;
              isAutoRetried: boolean;
              name: string;
              osName: string | null;
              profileId: string;
              profileName: string;
              queued: string | null;
              runMode: "recording" | "server" | "local";
              runProfileId: string | null;
              screenSizeType: "desktop" | "mobile" | "custom";
              section: "main" | "before_all" | "after_all";
              sequence: number | null;
              started: string | null;
              status:
                  | "error"
                  | "passed"
                  | "failed"
                  | "running"
                  | "auto_retrying"
                  | "stopped"
                  | "queued"
                  | "paused"
                  | "skipped"
                  | "recording"
                  | "initialized";
              suiteRunId: string
              | null;
              testId: string | null;
              triggeredBy:
                  | "user"
                  | "api"
                  | "webhook"
                  | "scheduler"
                  | "github"
                  | "cli"
                  | "agent";
              webappUrl: string;
          },
      >

      When the run does not complete within the timeout.

      const run = await sdk.tests.watchRunProgress(
        runId,
        (s) => console.log(`${s.status} ${s.finishedSteps}/${s.totalSteps}`),
        { pollInterval: 3000, timeout: 600_000 },
      );

    • Fetch a single debug artifact (e.g. HAR, network trace) for a run.

      Parameters

      • runId: string

        UUID of the run.

      • artifactType: "network_logs" | "logs" | "dom_snapshot"

        Artifact discriminator (e.g. 'har').

      • options: RequestOptions = {}

      Returns Promise<
          {
              id: string;
              kind: | "network_logs"
              | "logs"
              | "dom_snapshot"
              | "logs_partial"
              | "cloud_logs"
              | "container_stats"
              | "chrome_debug_logs";
              file: string;
              fileExtension: string
              | null;
              contentType: string | null;
              expirationTime: string | null;
          },
      >

    • Export a test as YAML (string) or ZIP (Uint8Array).

      Parameters

      • testId: string

        UUID of the test to export.

      • fmt: "yaml"

        'yaml' returns a string body; 'zip' returns binary bytes.

      • Optionaloptions: RequestOptions

      Returns Promise<string>

      YAML text or raw ZIP bytes, matching fmt.

      const yaml = await sdk.tests.export(testId, 'yaml');
      const zipBytes = await sdk.tests.export(testId, 'zip');

    • Export a test as YAML (string) or ZIP (Uint8Array).

      Parameters

      • testId: string

        UUID of the test to export.

      • fmt: "zip"

        'yaml' returns a string body; 'zip' returns binary bytes.

      • Optionaloptions: RequestOptions

      Returns Promise<Uint8Array<ArrayBufferLike>>

      YAML text or raw ZIP bytes, matching fmt.

      const yaml = await sdk.tests.export(testId, 'yaml');
      const zipBytes = await sdk.tests.export(testId, 'zip');

    • Import a single test from YAML (string) or ZIP (Uint8Array). Returns the created test summary.

      Parameters

      • payload: string | Uint8Array<ArrayBufferLike>

        YAML text or raw ZIP bytes.

      • fmt: "yaml" | "zip"

        Format matching payload ('yaml' or 'zip').

      • options: ImportTestOptions = {}
        • OptionalconflictMode?: string
        • Optionalsignal?: AbortSignal

          Abort signal for client-side cancellation. Throws CancellationError.

        • Optionaltimeout?: number

          Per-request timeout in milliseconds. Overrides BugBugConfig.timeout for this call only.

        • Optionalheaders?: Record<string, string>

          Per-request HTTP headers. These are merged first so the SDK's auth and User-Agent headers always win — supplying Authorization here will have no effect.

      Returns Promise<TestSummary>

      When the server rejects the payload.

      const yaml = await readFile('test.yaml', 'utf8');
      const test = await sdk.tests.import(yaml, 'yaml', { conflictMode: 'rename' });

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods