Skip to main content
Version: 1.x

Function: defineConfig()

defineConfig(base, environments?): object

Type helper for Praman config files with optional environment-specific overrides.

Parameters​

base​

Base config input applied in every environment.

ai?​

{ anthropicApiKey?: string; apiKey?: string; apiVersion?: string; deployment?: string; endpoint?: unknown; includeAriaSnapshot?: boolean; maxTokens?: number; model?: string; provider?: unknown; temperature?: number; } = ...

ai.anthropicApiKey?​

string = ...

ai.apiKey?​

string = ...

ai.apiVersion?​

string = ...

ai.deployment?​

string = ...

ai.endpoint?​

unknown = ...

ai.includeAriaSnapshot?​

boolean = ...

Include an aria snapshot in pramanAI.buildContext() output (Playwright 1.60+). On unless set to false.

ai.maxTokens?​

number = ...

ai.model?​

string = ...

ai.provider?​

unknown = ...

ai.temperature?​

number = ...

auth?​

{ baseUrl?: unknown; client?: string; language?: string; password?: string; strategy?: unknown; username?: string; } = ...

auth.baseUrl?​

unknown = ...

auth.client?​

string = ...

auth.language?​

string = ...

auth.password?​

string = ...

auth.strategy?​

unknown = ...

Auth strategy for SAP login.

Remarks

  • basic: On-premise form-based login (onprem-strategy)
  • btp-saml: BTP Cloud SAML via IAS (cloud-saml-strategy)
  • office365: Microsoft 365 / Azure AD SSO (office365-strategy)
  • custom: User-provided login function

For API-based, certificate, or multi-tenant auth, see the authentication guide — these are configured programmatically.

auth.username?​

string = ...

captureFailureArtifacts?​

boolean = ...

Whether to auto-capture diagnostic artifacts (screenshot, control tree, page context) on test failure.

Remarks

When true (default), the failure artifacts fixture automatically attaches a screenshot (PNG), UI5 control tree snapshot (JSON), and page metadata (JSON) to the test report on any test failure. Set to false to disable.

controlDiscoveryTimeout?​

number = ...

controlTreeCapture?​

{ enabled?: boolean; maxControls?: number; maxDepth?: number; } = ...

controlTreeCapture.enabled?​

boolean = ...

controlTreeCapture.maxControls?​

number = ...

controlTreeCapture.maxDepth?​

number = ...

defaultMatchSubclasses?​

boolean = ...

Default value for matchSubclasses on selectors that don't specify it.

discoveryStrategies?​

("direct-id" | "recordreplay" | "registry")[] = ...

ignoreAutoWaitUrls?​

string[] = ...

interactionStrategy?​

"ui5-native" | "dom-first" | "opa5" = ...

logLevel?​

"error" | "debug" | "warn" | "info" | "verbose" = ...

odataTracing?​

{ enabled?: boolean; urlPatterns?: string[]; } = ...

odataTracing.enabled?​

boolean = ...

odataTracing.urlPatterns?​

string[] = ...

opa5?​

{ autoWait?: boolean; debug?: boolean; interactionTimeout?: number; } = ...

opa5.autoWait?​

boolean = ...

opa5.debug?​

boolean = ...

opa5.interactionTimeout?​

number = ...

overlays?​

{ enabled?: boolean; } = ...

overlays.enabled?​

boolean = ...

Whether to register the built-in overlay rules.

Remarks

The built-ins are detect-only — they never dismiss anything. Disable this to register nothing automatically and drive overlays.register() yourself.

preferVisibleControls?​

boolean = ...

selectors?​

{ defaultTimeout?: number; preferVisibleControls?: boolean; skipStabilityWait?: boolean; } = ...

selectors.defaultTimeout?​

number = ...

Deprecated

Use top-level controlDiscoveryTimeout instead.

selectors.preferVisibleControls?​

boolean = ...

selectors.skipStabilityWait?​

boolean = ...

skipPostFillWait?​

boolean = ...

When true, fill() will not call waitForUI5() after entering text. Useful for rapid sequential fills where intermediate stability waits are unnecessary.

skipStabilityWait?​

boolean = ...

telemetry?​

{ batchTimeout?: number; connectionString?: string; endpoint?: string; exporter?: "otlp" | "azure-monitor" | "jaeger"; maxQueueSize?: number; metrics?: boolean; openTelemetry?: boolean; protocol?: "http" | "grpc"; resourceAttributes?: Record<string, string>; serviceName?: string; } = ...

telemetry.batchTimeout?​

number = ...

telemetry.connectionString?​

string = ...

Azure Monitor connection string. Required when exporter is 'azure-monitor'.

telemetry.endpoint?​

string = ...

telemetry.exporter?​

"otlp" | "azure-monitor" | "jaeger" = ...

telemetry.maxQueueSize?​

number = ...

telemetry.metrics?​

boolean = ...

telemetry.openTelemetry?​

boolean = ...

telemetry.protocol?​

"http" | "grpc" = ...

telemetry.resourceAttributes?​

Record<string, string> = ...

telemetry.serviceName?​

string = ...

ui5WaitTimeout?​

number = ...

environments?​

Record<string, Partial<{ ai?: { anthropicApiKey?: string; apiKey?: string; apiVersion?: string; deployment?: string; endpoint?: unknown; includeAriaSnapshot?: boolean; maxTokens?: number; model?: string; provider?: unknown; temperature?: number; }; auth?: { baseUrl?: unknown; client?: string; language?: string; password?: string; strategy?: unknown; username?: string; }; captureFailureArtifacts?: boolean; controlDiscoveryTimeout?: number; controlTreeCapture?: { enabled?: boolean; maxControls?: number; maxDepth?: number; }; defaultMatchSubclasses?: boolean; discoveryStrategies?: ("direct-id" | "recordreplay" | "registry")[]; ignoreAutoWaitUrls?: string[]; interactionStrategy?: "ui5-native" | "dom-first" | "opa5"; logLevel?: "error" | "debug" | "warn" | "info" | "verbose"; odataTracing?: { enabled?: boolean; urlPatterns?: string[]; }; opa5?: { autoWait?: boolean; debug?: boolean; interactionTimeout?: number; }; overlays?: { enabled?: boolean; }; preferVisibleControls?: boolean; selectors?: { defaultTimeout?: number; preferVisibleControls?: boolean; skipStabilityWait?: boolean; }; skipPostFillWait?: boolean; skipStabilityWait?: boolean; telemetry?: { batchTimeout?: number; connectionString?: string; endpoint?: string; exporter?: "otlp" | "azure-monitor" | "jaeger"; maxQueueSize?: number; metrics?: boolean; openTelemetry?: boolean; protocol?: "http" | "grpc"; resourceAttributes?: Record<string, string>; serviceName?: string; }; ui5WaitTimeout?: number; }>>

Optional map of environment names to partial config overrides. The active environment is read from PRAMAN_ENV first, then NODE_ENV.

Returns​

The resolved config input for the current environment.

ai?​

optional ai?: object

ai.anthropicApiKey?​

optional anthropicApiKey?: string

ai.apiKey?​

optional apiKey?: string

ai.apiVersion?​

optional apiVersion?: string

ai.deployment?​

optional deployment?: string

ai.endpoint?​

optional endpoint?: unknown

ai.includeAriaSnapshot?​

optional includeAriaSnapshot?: boolean

Include an aria snapshot in pramanAI.buildContext() output (Playwright 1.60+). On unless set to false.

ai.maxTokens?​

optional maxTokens?: number

ai.model?​

optional model?: string

ai.provider?​

optional provider?: unknown

ai.temperature?​

optional temperature?: number

auth?​

optional auth?: object

auth.baseUrl?​

optional baseUrl?: unknown

auth.client?​

optional client?: string

auth.language?​

optional language?: string

auth.password?​

optional password?: string

auth.strategy?​

optional strategy?: unknown

Auth strategy for SAP login.

Remarks​
  • basic: On-premise form-based login (onprem-strategy)
  • btp-saml: BTP Cloud SAML via IAS (cloud-saml-strategy)
  • office365: Microsoft 365 / Azure AD SSO (office365-strategy)
  • custom: User-provided login function

For API-based, certificate, or multi-tenant auth, see the authentication guide — these are configured programmatically.

auth.username?​

optional username?: string

captureFailureArtifacts?​

optional captureFailureArtifacts?: boolean

Whether to auto-capture diagnostic artifacts (screenshot, control tree, page context) on test failure.

Remarks​

When true (default), the failure artifacts fixture automatically attaches a screenshot (PNG), UI5 control tree snapshot (JSON), and page metadata (JSON) to the test report on any test failure. Set to false to disable.

controlDiscoveryTimeout?​

optional controlDiscoveryTimeout?: number

controlTreeCapture?​

optional controlTreeCapture?: object

controlTreeCapture.enabled?​

optional enabled?: boolean

controlTreeCapture.maxControls?​

optional maxControls?: number

controlTreeCapture.maxDepth?​

optional maxDepth?: number

defaultMatchSubclasses?​

optional defaultMatchSubclasses?: boolean

Default value for matchSubclasses on selectors that don't specify it.

discoveryStrategies?​

optional discoveryStrategies?: ("direct-id" | "recordreplay" | "registry")[]

ignoreAutoWaitUrls?​

optional ignoreAutoWaitUrls?: string[]

interactionStrategy?​

optional interactionStrategy?: "ui5-native" | "dom-first" | "opa5"

logLevel?​

optional logLevel?: "error" | "debug" | "warn" | "info" | "verbose"

odataTracing?​

optional odataTracing?: object

odataTracing.enabled?​

optional enabled?: boolean

odataTracing.urlPatterns?​

optional urlPatterns?: string[]

opa5?​

optional opa5?: object

opa5.autoWait?​

optional autoWait?: boolean

opa5.debug?​

optional debug?: boolean

opa5.interactionTimeout?​

optional interactionTimeout?: number

overlays?​

optional overlays?: object

overlays.enabled?​

optional enabled?: boolean

Whether to register the built-in overlay rules.

Remarks​

The built-ins are detect-only — they never dismiss anything. Disable this to register nothing automatically and drive overlays.register() yourself.

preferVisibleControls?​

optional preferVisibleControls?: boolean

selectors?​

optional selectors?: object

selectors.defaultTimeout?​

optional defaultTimeout?: number

Deprecated​

Use top-level controlDiscoveryTimeout instead.

selectors.preferVisibleControls?​

optional preferVisibleControls?: boolean

selectors.skipStabilityWait?​

optional skipStabilityWait?: boolean

skipPostFillWait?​

optional skipPostFillWait?: boolean

When true, fill() will not call waitForUI5() after entering text. Useful for rapid sequential fills where intermediate stability waits are unnecessary.

skipStabilityWait?​

optional skipStabilityWait?: boolean

telemetry?​

optional telemetry?: object

telemetry.batchTimeout?​

optional batchTimeout?: number

telemetry.connectionString?​

optional connectionString?: string

Azure Monitor connection string. Required when exporter is 'azure-monitor'.

telemetry.endpoint?​

optional endpoint?: string

telemetry.exporter?​

optional exporter?: "otlp" | "azure-monitor" | "jaeger"

telemetry.maxQueueSize?​

optional maxQueueSize?: number

telemetry.metrics?​

optional metrics?: boolean

telemetry.openTelemetry?​

optional openTelemetry?: boolean

telemetry.protocol?​

optional protocol?: "http" | "grpc"

telemetry.resourceAttributes?​

optional resourceAttributes?: Record<string, string>

telemetry.serviceName?​

optional serviceName?: string

ui5WaitTimeout?​

optional ui5WaitTimeout?: number

Remarks​

Used in praman.config.ts for IDE autocomplete and type checking. When environments is provided, the active environment is determined by PRAMAN_ENV (takes precedence) or NODE_ENV. If the active environment matches a key in environments, that override is shallow-merged onto base — nested objects such as auth or ai are replaced entirely, not deep-merged.

Guarantee​

Returns base unchanged when no environment matches or environments is omitted; returns a shallow merge otherwise.

Example​

// praman.config.ts
import { defineConfig } from 'playwright-praman';

export default defineConfig(
{ logLevel: 'info', ui5WaitTimeout: 30_000 },
{
ci: { logLevel: 'error', skipStabilityWait: true },
development: { logLevel: 'debug' },
},
);