TypeScript Types - BrowserTest

Core Types

BrowserTestConfig

Configuration options for the BrowserTest client.

interface BrowserTestConfig {
  /** API key for authentication */
  apiKey: string;
  /** Base URL for API calls (default: https://api.browsertest.in) */
  baseUrl?: string;
  /** Request timeout in milliseconds (default: 30000) */
  timeout?: number;
  /** Number of retries for failed requests (default: 3) */
  retries?: number;
}

QuotaInfo

Usage and quota information.

interface QuotaInfo {
  plan: string;
  usage: {
    screenshot: {
      used: number;
      limit: number;
      remaining: number;
    };
    agentic: {
      used: number;
      limit: number;
      remaining: number;
    };
    total: {
      screenshot: number;
      agentic: number;
    };
  };
}

Screenshot Types

ScreenshotOptions

Configuration options for screenshot capture.

interface ScreenshotOptions {
  /** URL to screenshot */
  url: string;
  /** Capture full page (default: false) */
  fullPage?: boolean;
  /** Viewport width (default: 1280) */
  width?: number;
  /** Viewport height (default: 720) */
  height?: number;
  /** Image format: 'png' | 'jpeg' (default: 'png') */
  format?: 'png' | 'jpeg';
  /** Image quality for JPEG (default: 80) */
  quality?: number;
  /** Wait time in milliseconds before screenshot (default: 0) */
  waitFor?: number;
  /** CSS selector for element screenshot (optional) */
  selector?: string | null;
  /** Request timeout in milliseconds (default: 10000) */
  timeout?: number;
  /** Block ads and trackers (default: true) */
  blockAds?: boolean;
}

ScreenshotResult

Result of a screenshot operation.

interface ScreenshotResult {
  success: boolean;
  data: {
    screenshot: string; // base64 encoded image
    url: string;
    title: string;
    width: number;
    height: number;
    format: string;
    fullPage: boolean;
  };
  meta: {
    timeMs: number;
    size: number;
  };
}

BatchScreenshotOptions

Options for batch screenshot operations.

interface BatchScreenshotOptions extends Omit<ScreenshotOptions, 'url'> {
  /** Array of URLs to screenshot */
  urls: string[];
}

BatchScreenshotResult

Result of a batch screenshot operation.

interface BatchScreenshotResult {
  success: boolean;
  results: Array<{
    url: string;
    success: boolean;
    data?: ScreenshotResult['data'];
    error?: string;
  }>;
  meta: {
    total: number;
    successful: number;
    timeMs: number;
  };
}

Testing Types

TestOptions

Configuration options for test execution.

interface TestOptions {
  /** Natural language test instructions */
  instructions: string;
  /** URL to test */
  url: string;
  /** JSON schema for structured output (optional) */
  outputSchema?: object;
  /** Test configuration */
  config?: TestConfig;
}

TestConfig

Browser and test configuration.

interface TestConfig {
  /** Viewport width (default: 1280) */
  width?: number;
  /** Viewport height (default: 720) */
  height?: number;
  /** Wait time before starting test (default: 0) */
  waitFor?: number;
  /** Test timeout in milliseconds (default: 30000) */
  timeout?: number;
  /** Block ads and trackers (default: true) */
  blockAds?: boolean;
  /** User agent string (optional) */
  userAgent?: string;
}

TestResult

Result of a test execution.

interface TestResult {
  success: boolean;
  results: {
    /** Agent actions performed during test */
    actions: Array<{
      type: string;
      description: string;
      timestamp: string;
    }>;
    /** Structured data if outputSchema was provided */
    structuredData?: any;
    /** Raw test output */
    output: string;
  };
  meta: {
    timeMs: number;
    url: string;
  };
}

TestJob

Information about an async test job.

interface TestJob {
  jobId: string;
  status: 'pending' | 'running' | 'completed' | 'failed';
  createdAt: string;
  url: string;
}

TestJobStatus

Detailed status of a test job.

interface TestJobStatus {
  job: {
    id: string;
    status: 'pending' | 'running' | 'completed' | 'failed';
    createdAt: string;
    startedAt?: string;
    completedAt?: string;
    url: string;
    config?: TestConfig;
    results?: TestResult['results'];
    error?: string;
    progress?: string;
  };
}

ListTestsOptions

Options for listing test jobs.

interface ListTestsOptions {
  /** Filter by status */
  status?: 'pending' | 'running' | 'completed' | 'failed';
  /** Filter by template ID */
  templateId?: string;
  /** Maximum number of results */
  limit?: number;
  /** Number of results to skip */
  offset?: number;
  /** Sort order (default: 'desc') */
  sortOrder?: 'asc' | 'desc';
}

TestJobsList

List of test jobs.

interface TestJobsList {
  jobs: Array<{
    id: string;
    status: string;
    createdAt: string;
    completedAt?: string;
    url: string;
    templateId?: string;
    results?: TestResult['results'];
    error?: string;
  }>;
  total: number;
  hasMore: boolean;
}

Template Types

TemplateOptions

Options for creating a test template.

interface TemplateOptions {
  /** Template name */
  name: string;
  /** Template description */
  description: string;
  /** Test instructions */
  instructions: string;
  /** JSON schema for structured output */
  outputSchema: object;
  /** Template tags for organization */
  tags?: string[];
}

TemplateResponse

Response from template creation/update.

interface TemplateResponse {
  template: {
    id: string;
    name: string;
    description: string;
    instructions: string;
    outputSchema: object;
    tags: string[];
    createdAt: string;
    updatedAt: string;
  };
}

TemplateInvocationOptions

Options for invoking a template.

interface TemplateInvocationOptions {
  /** URL to test */
  url: string;
  /** Test configuration overrides */
  config?: TestConfig;
  /** Parameter values for template variables */
  parameters?: Record<string, any>;
}

TemplateJobResponse

Response from template invocation.

interface TemplateJobResponse {
  jobId: string;
  status: 'pending' | 'running' | 'completed' | 'failed';
  createdAt: string;
  url: string;
}

TemplateListOptions

Options for listing templates.

interface TemplateListOptions {
  /** Search query for template names */
  search?: string;
  /** Filter by tags */
  tags?: string[];
  /** Maximum number of results */
  limit?: number;
  /** Number of results to skip */
  offset?: number;
  /** Sort order */
  sortOrder?: 'asc' | 'desc';
}

TemplateListResponse

List of templates.

interface TemplateListResponse {
  templates: Array<{
    id: string;
    name: string;
    description: string;
    tags: string[];
    createdAt: string;
    updatedAt: string;
  }>;
  total: number;
  hasMore: boolean;
}

Batch Types

ScreenshotRequest

Request configuration for a single screenshot in a batch.

interface ScreenshotRequest {
  /** URL to screenshot */
  url: string;
  /** Full page capture (default: false) */
  fullPage?: boolean;
  /** Viewport width (default: 1280) */
  width?: number;
  /** Viewport height (default: 720) */
  height?: number;
  /** Image format: 'png' | 'jpeg' (default: 'png') */
  format?: 'png' | 'jpeg';
  /** Image quality for JPEG (default: 80) */
  quality?: number;
  /** Wait time before screenshot (default: 0) */
  waitFor?: number;
  /** CSS selector for element screenshot */
  selector?: string | null;
  /** Request timeout in milliseconds (default: 10000) */
  timeout?: number;
  /** Block ads and trackers (default: true) */
  blockAds?: boolean;
}

TestRequest

Request configuration for a single test in a batch.

interface TestRequest {
  /** Test instructions */
  instructions: string;
  /** URL to test */
  url: string;
  /** JSON schema for structured output */
  outputSchema?: object;
  /** Test configuration */
  config?: TestConfig;
}

BatchOptions

Options for batch processing.

interface BatchOptions {
  /** Maximum concurrent operations (default: 3) */
  concurrency?: number;
  /** Continue processing on individual failures (default: true) */
  continueOnError?: boolean;
  /** Overall batch timeout in milliseconds */
  timeout?: number;
}

BatchScreenshotResults

Results from batch screenshot processing.

interface BatchScreenshotResults {
  successful: number;
  total: number;
  results: Array<{
    url: string;
    success: boolean;
    data?: ScreenshotResult['data'];
    error?: string;
    timeMs?: number;
  }>;
  meta: {
    totalTimeMs: number;
    averageTimeMs: number;
    concurrencyUsed: number;
  };
}

BatchTestResults

Results from batch test processing.

interface BatchTestResults {
  successful: number;
  total: number;
  results: Array<{
    instructions: string;
    url: string;
    success: boolean;
    data?: TestResult['results'];
    error?: string;
    timeMs?: number;
  }>;
  meta: {
    totalTimeMs: number;
    averageTimeMs: number;
    concurrencyUsed: number;
  };
}

BatchJobResults

Results from batch job creation.

interface BatchJobResults {
  jobs: Array<{
    jobId: string;
    status: 'pending' | 'running' | 'completed' | 'failed';
    url: string;
    instructions: string;
  }>;
  meta: {
    total: number;
    created: number;
    failed: number;
  };
}

Error Types

BrowserTestError

Base error class for SDK errors.

class BrowserTestError extends Error {
  constructor(message: string, public status?: number) {
    super(message);
    this.name = 'BrowserTestError';
  }
}

BrowserTestAuthError

Authentication-related errors.

class BrowserTestAuthError extends BrowserTestError {
  constructor(message = 'Authentication failed') {
    super(message);
    this.name = 'BrowserTestAuthError';
  }
}

BrowserTestQuotaError

Quota and billing-related errors.

class BrowserTestQuotaError extends BrowserTestError {
  constructor(message = 'Quota exceeded', public quotaInfo?: QuotaInfo) {
    super(message);
    this.name = 'BrowserTestQuotaError';
  }
}

BrowserTestAPIError

API-related errors.

class BrowserTestAPIError extends BrowserTestError {
  constructor(message: string, status: number) {
    super(message, status);
    this.name = 'BrowserTestAPIError';
  }
}

BrowserTestTimeoutError

Timeout-related errors.

class BrowserTestTimeoutError extends BrowserTestError {
  constructor(message = 'Request timed out') {
    super(message);
    this.name = 'BrowserTestTimeoutError';
  }
}

Utility Types

ApiResponse

Generic API response wrapper.

interface ApiResponse<TData = unknown, TError = string> {
  success: boolean;
  data?: TData;
  error?: TError;
  meta?: {
    timeMs: number;
    requestId?: string;
  };
}

Successful Results

Type helpers for extracting successful results.

// Extract successful screenshot results
type SuccessfulScreenshot = ScreenshotResult & { success: true };

// Extract successful test results
type SuccessfulTest = TestResult & { success: true };

// Extract data from successful results
type ScreenshotData = SuccessfulScreenshot['data'];
type TestResults = SuccessfulTest['results'];

Batch Result Types

Type helpers for batch operations.

// Generic batch result
type BatchResult<TData, TError = string> = Array<{
  success: true;
  data: TData;
} | {
  success: false;
  error: TError;
}>;

// Specific batch types
type ScreenshotBatchResult = BatchResult<ScreenshotResult['data']>;
type TestBatchResult = BatchResult<TestResult['results']>;

Configuration Types

Environment-based configuration types.

type Environment = 'development' | 'staging' | 'production';

interface EnvironmentConfig extends BrowserTestConfig {
  environment: Environment;
}

// Union type for all possible config variations
type BrowserTestConfigUnion =
  | BrowserTestConfig
  | EnvironmentConfig;

Advanced Types

Generic Test Types

// Generic test result with typed structured data
interface TypedTestResult<TOutput = any> extends Omit<TestResult, 'results'> {
  results: Omit<TestResult['results'], 'structuredData'> & {
    structuredData: TOutput;
  };
}

// Usage with specific output types
interface LoginTestOutput {
  loginSuccessful: boolean;
  userName?: string;
  errorMessage?: string;
}

type LoginTestResult = TypedTestResult<LoginTestOutput>;

Template Types

// Generic template with typed output
interface TypedTemplate<TOutput = any> extends Omit<TemplateOptions, 'outputSchema'> {
  outputSchema: object; // JSON schema for TOutput
  outputType?: TOutput; // Type hint (not used at runtime)
}

// Template invocation with typed parameters
interface TypedTemplateInvocation<TPayload = any> extends TemplateInvocationOptions {
  parameters: TPayload;
}

Batch Processing Types

// Batch processor configuration
interface BatchProcessorConfig {
  concurrency: number;
  timeout: number;
  retryPolicy: {
    maxRetries: number;
    backoffMs: number;
  };
}

// Batch processing result
interface BatchProcessingResult<TData, TError = string> {
  successful: TData[];
  failed: Array<{
    item: unknown;
    error: TError;
    retries: number;
  }>;
  stats: {
    total: number;
    successful: number;
    failed: number;
    durationMs: number;
    throughput: number; // items per second
  };
}

Event Types

// Event types for monitoring
type BatchEvent =
  | { type: 'batch_started'; batchId: string; totalItems: number }
  | { type: 'item_completed'; batchId: string; itemIndex: number; success: boolean }
  | { type: 'batch_completed'; batchId: string; stats: BatchProcessingResult<any>['stats'] }
  | { type: 'batch_failed'; batchId: string; error: string };

// Job event types
type JobEvent =
  | { type: 'job_created'; jobId: string; templateId?: string }
  | { type: 'job_started'; jobId: string }
  | { type: 'job_progress'; jobId: string; progress: string }
  | { type: 'job_completed'; jobId: string; results: TestResult['results'] }
  | { type: 'job_failed'; jobId: string; error: string };

Type Guards

Runtime type checking functions.

// Check if result is successful
function isSuccessfulScreenshot(result: ScreenshotResult): result is SuccessfulScreenshot {
  return result.success;
}

function isSuccessfulTest(result: TestResult): result is SuccessfulTest {
  return result.success;
}

// Check error types
function isBrowserTestAuthError(error: unknown): error is BrowserTestAuthError {
  return error instanceof Error && error.name === 'BrowserTestAuthError';
}

function isBrowserTestQuotaError(error: unknown): error is BrowserTestQuotaError {
  return error instanceof Error && error.name === 'BrowserTestQuotaError';
}

function isBrowserTestAPIError(error: unknown): error is BrowserTestAPIError {
  return error instanceof Error && error.name === 'BrowserTestAPIError';
}

function isBrowserTestTimeoutError(error: unknown): error is BrowserTestTimeoutError {
  return error instanceof Error && error.name === 'BrowserTestTimeoutError';
}

Type Utilities

Extract and Transform

// Extract URL from various request types
type ExtractUrl<T> = T extends { url: string } ? T['url'] : never;

// Extract instructions from test requests
type ExtractInstructions<T> = T extends { instructions: string } ? T['instructions'] : never;

// Create union of all possible result data types
type ResultData = ScreenshotResult['data'] | TestResult['results'];

// Extract error messages
type ErrorMessage = string;

Conditional Types

// Create result type based on operation type
type OperationResult<TOperation extends string, TData> =
  TOperation extends 'screenshot' ? ScreenshotResult :
  TOperation extends 'test' ? TestResult :
  TOperation extends 'batch' ? BatchScreenshotResults | BatchTestResults :
  never;

// Check if type has specific property
type HasProperty<T, K extends string> = K extends keyof T ? true : false;

// Make specific properties optional
type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

Migration Types

Types for handling API changes and versioning.

// Version-specific types
interface ScreenshotResultV1 {
  success: boolean;
  screenshot: string;
  url: string;
  width: number;
  height: number;
}

// Migration helper
type MigrateScreenshotResultV1ToV2 = (v1: ScreenshotResultV1) => ScreenshotResult;

// Backwards compatibility types
type ScreenshotResultLatest = ScreenshotResult;
type ScreenshotResultLegacy = ScreenshotResultV1 | ScreenshotResult;

// Version detection
function isLatestScreenshotResult(result: ScreenshotResultLegacy): result is ScreenshotResultLatest {
  return 'data' in result && 'meta' in result;
}

Best Practices

Type Safety

Always use strict TypeScript settings
Define interfaces for structured output
Use discriminated unions for results
Create type guards for runtime checks
Leverage generic types for reusable code

Development Experience

// Enable comprehensive TypeScript configuration
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noUncheckedIndexedAccess": true
  }
}

IntelliSense Optimization

// Use JSDoc comments for better IntelliSense
/**
 * Takes a screenshot of the specified URL with customizable options
 * @param options - Screenshot configuration options
 * @returns Promise resolving to screenshot result with type safety
 */
async function takeScreenshot(options: ScreenshotOptions): Promise<ScreenshotResult> {
  return bt.screenshot.take(options);
}

// IntelliSense will show parameter descriptions and types
const result = await takeScreenshot({
  url: 'https://example.com',
  fullPage: true, // Shows: "Capture full page (default: false)"
  format: 'png'   // Shows: "'png' | 'jpeg'"
});

Error Type Narrowing

// Type-safe error handling
async function handleBrowserTestOperation() {
  try {
    const result = await bt.screenshot.take({ url: 'https://example.com' });
    return result; // TypeScript knows result is ScreenshotResult
  } catch (error) {
    if (isBrowserTestAuthError(error)) {
      // TypeScript knows error is BrowserTestAuthError
      console.error('Auth failed:', error.message);
      throw error;
    }

    if (isBrowserTestQuotaError(error)) {
      // TypeScript knows error has quotaInfo property
      console.error('Quota exceeded:', error.quotaInfo);
      throw error;
    }

    // Handle other errors
    throw error;
  }
}

​Core Types

​BrowserTestConfig

​QuotaInfo

​Screenshot Types

​ScreenshotOptions

​ScreenshotResult

​BatchScreenshotOptions

​BatchScreenshotResult

​Testing Types

​TestOptions

​TestConfig

​TestResult

​TestJob

​TestJobStatus

​ListTestsOptions

​TestJobsList

​Template Types

​TemplateOptions

​TemplateResponse

​TemplateInvocationOptions

​TemplateJobResponse

​TemplateListOptions

​TemplateListResponse

​Batch Types

​ScreenshotRequest

​TestRequest

​BatchOptions

​BatchScreenshotResults

​BatchTestResults

​BatchJobResults

​Error Types

​BrowserTestError

​BrowserTestAuthError

​BrowserTestQuotaError

​BrowserTestAPIError

​BrowserTestTimeoutError

​Utility Types

​ApiResponse

​Successful Results

​Batch Result Types

​Configuration Types

​Advanced Types

​Generic Test Types

​Template Types

​Batch Processing Types

​Event Types

​Type Guards

​Type Utilities

​Extract and Transform

​Conditional Types

​Migration Types

​Best Practices

​Type Safety

​Development Experience

​IntelliSense Optimization

​Error Type Narrowing

Core Types

BrowserTestConfig

QuotaInfo

Screenshot Types

ScreenshotOptions

ScreenshotResult

BatchScreenshotOptions

BatchScreenshotResult

Testing Types

TestOptions

TestConfig

TestResult

TestJob

TestJobStatus

ListTestsOptions

TestJobsList

Template Types

TemplateOptions

TemplateResponse

TemplateInvocationOptions

TemplateJobResponse

TemplateListOptions

TemplateListResponse

Batch Types

ScreenshotRequest

TestRequest

BatchOptions

BatchScreenshotResults

BatchTestResults

BatchJobResults

Error Types

BrowserTestError

BrowserTestAuthError

BrowserTestQuotaError

BrowserTestAPIError

BrowserTestTimeoutError

Utility Types

ApiResponse

Successful Results

Batch Result Types

Configuration Types

Advanced Types

Generic Test Types

Template Types

Batch Processing Types

Event Types

Type Guards

Type Utilities

Extract and Transform

Conditional Types

Migration Types

Best Practices

Type Safety

Development Experience

IntelliSense Optimization

Error Type Narrowing