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

    Class SuitesModule

    Suites module — manage BugBug test suites and their runs.

    Mirrors the shape of TestsModule: CRUD over /suites/ + run lifecycle over /suiteruns/. Use startRun for the recommended high-level entry point with optional progress watching.

    Index

    Constructors

    constructor

    Methods

    list getAll get create update partialUpdate delete startRun getRun listRuns getRecentRuns getRunProgress stopRun getRunScreenshots downloadRunJunitReport listRunDebugArtifacts watchRunProgress

    Constructors

    • Parameters

      • client: BugBugApiClient

      Returns SuitesModule

    Methods

    • List suites with pagination, search, and ordering.

      Parameters

      • options: ListSuitesOptions = {}
        • 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<SuitesListResponse>

      Paginated SuitesListResponse envelope (validated via Zod).

      On Zod validation failure.

    • Fetch a single suite by ID.

      Parameters

      Returns Promise<Suite>

      When no suite matches suiteId.

    • Create a new suite.

      Parameters

      • data: {
            autoAddNewTests?: boolean;
            autoRetry?: number;
            beforeAfterAllEnabled?: boolean;
            notes?: string | null;
            name?: string | null;
            runInParallel?: boolean;
            runProfileId: string;
            tests?: string[];
            beforeAll?: string[];
            afterAll?: string[];
        }
        • OptionalautoAddNewTests?: boolean
        • OptionalautoRetry?: number
        • OptionalbeforeAfterAllEnabled?: boolean
        • Optionalnotes?: string | null

          Suite notes

        • Optionalname?: string | null
        • OptionalrunInParallel?: boolean
        • runProfileId: string

          Format: uuid

        • Optionaltests?: string[]
        • OptionalbeforeAll?: string[]
        • OptionalafterAll?: string[]
      • options: RequestOptions = {}

      Returns Promise<Suite>

      On invalid payload.

    • Fully replace a suite via PUT (all fields required). Use partialUpdate for sparse PATCH semantics.

      Parameters

      • suiteId: string
      • data: {
            autoAddNewTests?: boolean;
            autoRetry?: number;
            beforeAfterAllEnabled?: boolean;
            notes?: string | null;
            name?: string | null;
            runInParallel?: boolean;
            runProfileId: string;
            tests?: string[];
            beforeAll?: string[];
            afterAll?: string[];
        }
        • OptionalautoAddNewTests?: boolean
        • OptionalautoRetry?: number
        • OptionalbeforeAfterAllEnabled?: boolean
        • Optionalnotes?: string | null

          Suite notes

        • Optionalname?: string | null
        • OptionalrunInParallel?: boolean
        • runProfileId: string

          Format: uuid

        • Optionaltests?: string[]
        • OptionalbeforeAll?: string[]
        • OptionalafterAll?: string[]
      • options: RequestOptions = {}

      Returns Promise<Suite>

      When the suite does not exist.

      On invalid payload.

    • Patch selected fields on a suite (PATCH semantics).

      Parameters

      • suiteId: string
      • data: {
            autoAddNewTests?: boolean;
            autoRetry?: number;
            beforeAfterAllEnabled?: boolean;
            notes?: string | null;
            name?: string | null;
            runInParallel?: boolean;
            runProfileId?: string;
            tests?: string[];
            beforeAll?: string[];
            afterAll?: string[];
        }
        • OptionalautoAddNewTests?: boolean
        • OptionalautoRetry?: number
        • OptionalbeforeAfterAllEnabled?: boolean
        • Optionalnotes?: string | null

          Suite notes

        • Optionalname?: string | null
        • OptionalrunInParallel?: boolean
        • OptionalrunProfileId?: string

          Format: uuid

        • Optionaltests?: string[]
        • OptionalbeforeAll?: string[]
        • OptionalafterAll?: string[]
      • options: RequestOptions = {}

      Returns Promise<Suite>

      When the suite does not exist.

      On invalid payload.

    • Delete a suite by ID.

      Parameters

      Returns Promise<void>

      When the suite does not exist.

    • Start a suite run, optionally watching progress until completion.

      Parameters

      • suiteId: string

        UUID of the suite to run.

      • options: RunSuiteWatchProgressOptions
        • 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;
                  status:
                      | "error"
                      | "passed"
                      | "failed"
                      | "running"
                      | "auto_retrying"
                      | "stopped"
                      | "queued"
                      | "paused"
                      | "skipped"
                      | "recording"
                      | "initialized";
                  finishedTests: number;
                  totalTests: number;
                  modified: string;
                  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<
          {
              beforeAfterAllEnabled: boolean;
              duration: string
              | null;
              ended: string | null;
              errorCode: string | null;
              id: string;
              name: string;
              parallelRun: boolean | null;
              parallelSlots: number | null;
              profileId: string;
              profileName: string;
              queued: string | null;
              runMode: "recording" | "server" | "local";
              sequence: number | null;
              started: string | null;
              status:
                  | "error"
                  | "passed"
                  | "failed"
                  | "running"
                  | "auto_retrying"
                  | "stopped"
                  | "queued"
                  | "paused"
                  | "skipped"
                  | "recording"
                  | "initialized";
              suiteId: string
              | null;
              testRuns: {
                  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;
              }[];
              triggeredBy: string;
              userId: string
              | null;
              webappUrl: string;
          },
      >

      When profileName does not resolve.

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

      const run = await sdk.suites.startRun(suiteId, {
        watchProgress: true,
        profileName: 'Production',
        onProgress: (s) => console.log(`${s.status} ${s.finishedTests}/${s.totalTests}`),
      });

    • Start a suite run, optionally watching progress until completion.

      Parameters

      • suiteId: string

        UUID of the suite to run.

      • Optionaloptions: RunSuiteNoWatchProgressOptions
        • 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;
              status: | "error"
              | "passed"
              | "failed"
              | "running"
              | "auto_retrying"
              | "stopped"
              | "queued"
              | "paused"
              | "skipped"
              | "recording"
              | "initialized";
              finishedTests: number;
              totalTests: number;
              modified: string;
              webappUrl: string;
              duration: string
              | null;
          },
      >

      When profileName does not resolve.

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

      const run = await sdk.suites.startRun(suiteId, {
        watchProgress: true,
        profileName: 'Production',
        onProgress: (s) => console.log(`${s.status} ${s.finishedTests}/${s.totalTests}`),
      });

    • Fetch full suite-run details including child test runs.

      Parameters

      Returns Promise<
          {
              beforeAfterAllEnabled: boolean;
              duration: string
              | null;
              ended: string | null;
              errorCode: string | null;
              id: string;
              name: string;
              parallelRun: boolean | null;
              parallelSlots: number | null;
              profileId: string;
              profileName: string;
              queued: string | null;
              runMode: "recording" | "server" | "local";
              sequence: number | null;
              started: string | null;
              status:
                  | "error"
                  | "passed"
                  | "failed"
                  | "running"
                  | "auto_retrying"
                  | "stopped"
                  | "queued"
                  | "paused"
                  | "skipped"
                  | "recording"
                  | "initialized";
              suiteId: string
              | null;
              testRuns: {
                  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;
              }[];
              triggeredBy: string;
              userId: string
              | null;
              webappUrl: string;
          },
      >

      When the run does not exist.

    • Get recent suite runs within a time window

      Parameters

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

      Returns Promise<SuiteRunsListResponse>

    • Fetch only the lightweight status of a suite run. Prefer this over getRun when polling.

      Parameters

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

    • Request cancellation of an in-progress suite run.

      Parameters

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

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

    • Fetch screenshots captured across all child test runs of a suite run.

      Parameters

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

    • Download the combined JUnit XML report for a suite run, aggregating all child test runs.

      Parameters

      Returns Promise<string>

      The JUnit report body as a string.

    • Poll a suite run's lightweight /status/ endpoint until it reaches a terminal status, then return the full SuiteRun once.

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

      Parameters

      • runId: string

        UUID of the suite run.

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

        Invoked on every successful poll with the latest SuiteRunState (including the terminal one). Receives finishedTests/totalTests/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 600_000 = 10 minutes; suites typically take longer than single tests).

        • 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<
          {
              beforeAfterAllEnabled: boolean;
              duration: string
              | null;
              ended: string | null;
              errorCode: string | null;
              id: string;
              name: string;
              parallelRun: boolean | null;
              parallelSlots: number | null;
              profileId: string;
              profileName: string;
              queued: string | null;
              runMode: "recording" | "server" | "local";
              sequence: number | null;
              started: string | null;
              status:
                  | "error"
                  | "passed"
                  | "failed"
                  | "running"
                  | "auto_retrying"
                  | "stopped"
                  | "queued"
                  | "paused"
                  | "skipped"
                  | "recording"
                  | "initialized";
              suiteId: string
              | null;
              testRuns: {
                  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;
              }[];
              triggeredBy: string;
              userId: string
              | null;
              webappUrl: string;
          },
      >

      When the run does not complete in time.

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods