Common Framework Features

robo-appian is the Appian-facing automation package, but Appian tests also receive a set of common automation capabilities supplied by robo-automation. You can use these capabilities through the robo-appian public boundary without importing lower-level robo-automation classes into application test code.

This guide summarizes the common functionality available to a robo-appian consumer and identifies where each responsibility lives.

Capability map

Capability	Available to `robo-appian` users	Primary owner
Browser and context lifecycle	Yes	`robo-automation`
Appian-specialized `page` fixture	Yes	`robo-appian`
framework timeout configuration	Yes	`robo-automation`
Pytest plugin and fixtures	Yes	Both packages
Worker/test correlation context	Yes	`robo-automation`, exposed by `robo-appian.runtime`
Framework logging	Yes	`robo-automation`
Performance/action timing	Yes	`robo-automation`
Before/after action snapshots	Yes	`robo-automation`
Appian semantic components	Yes	`robo-appian`
Appian-specific errors	Yes	`robo-appian`
Application/test failure snapshots	Application controlled	Consuming application (for example a consuming test project)

Browser and context lifecycle

Normal tests should request page and let the framework own browser, context, page creation, and teardown:

from robo_appian import AppianPage


def test_example(page: AppianPage) -> None:
    page.goto("https://your-appian-site.example/")
    page.button(name="Submit").is_visible()

robo-automation manages the test runtime. Application tests should use the provided fixtures and let the framework manage setup and cleanup.

See Browser Management and Pytest Integration.

Configuration flags and timeouts

robo-appian uses the common runtime configuration supplied by robo-automation. The most commonly used flags are:

Flag	Default	Usage
`BROWSER`	`chromium`	Select `chromium`, `firefox`, or `webkit`.
`HEAD_LESS`	`Y`	Set `N` to show the browser during local debugging.
`WAIT_TIME`	`90`	Default framework timeout in seconds.
`CAPTURE_ACTION_SNAPSHOTS`	`N`	Capture before/after evidence for instrumented actions.
`CAPTURE_FAILURE_SNAPSHOTS`	`N`	Capture failure evidence independently of action capture.
`CAPTURE_SNAPSHOT_IMAGES`	`Y`	Include PNG images in enabled action/failure snapshots; `N` skips PNG images.
`CAPTURE_SNAPSHOT_HTML`	`Y`	Include live HTML DOM in enabled action/failure snapshots.
`SNAPSHOT_FULL_PAGE`	`N`	Capture the full page instead of only the visible area.
`SNAPSHOT_PATH`	`${ARTIFACTS_ROOT}/snapshots`	Folder where screenshots are saved.
`PYTEST_LOG_LEVEL`	`INFO`	Set the framework/file logging level.
`TESTCASE_LOG_ENABLED`	`Y`	Enable per-testcase logs.
`PERF_MONITOR_ENABLED`	`Y`	Enable common performance monitoring.

Example:

BROWSER=chromium
HEAD_LESS=Y
WAIT_TIME=90
CAPTURE_ACTION_SNAPSHOTS=N
CAPTURE_FAILURE_SNAPSHOTS=Y
SNAPSHOT_PATH=${ARTIFACTS_ROOT}/snapshots

WAIT_TIME is expressed in seconds. A semantic component can override the normal action timeout with timeout=<seconds>. Enabled-state checks are intentionally different: component.is_enabled() is immediate, while component.is_enabled(timeout=8) waits up to eight seconds and returns False on timeout.

Application URLs, credentials, authentication policy, and test-data paths belong in the consuming application rather than in robo-appian.

Pytest fixtures

When installed normally or as an editable dependency, the pytest plugins are discovered through package entry points. A consumer normally does not need pytest_plugins or a manual -p option.

The important Appian-facing fixture is:

page: AppianPage

Lower-level browser/context resources remain framework-managed. Applications can override application policy while consuming the provided Appian page fixture.

See Pytest Integration.

Correlation and worker context

Parallel execution needs stable identifiers for logs, evidence, performance records, and authentication/session policy. robo-appian.runtime exposes the common correlation context without requiring application code to import robo-automation directly:

from robo_appian.runtime import current_automation_context

context = current_automation_context()

The context can identify values such as the testcase, process/attempt, and pytest-xdist worker. This keeps artifacts from concurrent workers separable and supports future per-worker credential isolation.

See Runtime API.

Logging

Framework/browser operations can participate in the common automation logging pipeline. Application projects can configure their own pytest log levels, formats, and artifact locations while the lower layer provides consistent action/runtime context.

Do not log passwords, tokens, authenticated storage-state contents, or other secrets. When a component action contains sensitive input, diagnostics should record the action and target while redacting the sensitive value.

Performance telemetry

The common automation layer can measure framework lifecycle and browser action durations. robo-appian component operations benefit from that instrumentation because their browser interactions ultimately execute through the shared automation layer.

An Appian semantic operation can involve more than one low-level action. For example, filling an Appian date can include the input update and the required focus-out/blur operation. Performance records therefore describe the underlying browser actions as well as the higher-level test flow.

Action snapshots

When action snapshots are enabled, supported browser actions can capture a before and after evidence pair:

CAPTURE_ACTION_SNAPSHOTS=Y

The normal lifecycle is always:

before -> action -> after

If the action fails, the after metadata records status=failed and error details. There is no separate after_error phase.

Appian component operations automatically benefit from this common instrumentation; application tests do not need to add screenshot calls around every component action.

See Action Snapshots for artifact layout, metadata, supported behavior, and performance considerations.

Failure snapshots are separate

Action and failure snapshots are two independent policies of the common robo-automation SnapshotService:

CAPTURE_FAILURE_SNAPSHOTS=Y

CAPTURE_FAILURE_SNAPSHOTS remains effective when action snapshots are disabled. When both flags are enabled, matching failed-action/test-failure evidence is deduplicated.

Error handling

robo-appian exposes RoboAppianError for Appian-specific failures while preserving the common automation error boundary underneath it. Application projects can derive their own errors for application policy without coupling tests to low-level implementation classes.

from robo_appian import RoboAppianError

try:
    page.checkbox(label="Acknowledgement").check()
except RoboAppianError as exc:
    print(exc)

See Handling Errors and Errors API.

Parallel execution and isolation

The shared lifecycle is compatible with pytest-xdist. Browser contexts, correlation data, logs, snapshots, and application authentication state should remain worker-aware.

A consuming application can assign different credentials or storage state to each worker. Do not introduce shared browser-context/session reuse that would force multiple workers to use one authenticated identity.

Appian-specific functionality remains in `robo-appian`

Common framework services should not replace Appian semantics. Continue to use the Appian component API for application interactions:

page.textbox(label="Description").fill("Example item")
page.checkbox(label="IT").check()
page.radio(label="Priority").select("High")
page.date(label="From").fill("12/12/2026")

This separation keeps application code readable: robo-automation owns reusable automation infrastructure, while robo-appian owns Appian-specific component discovery, state, rerender handling, and interaction semantics.

Wait for Appian processing

When a workflow step explicitly needs to wait for Appian's global processing to finish, call the page method directly:

page.wait_for_appian_action_completed()
page.wait_for_appian_action_completed(timeout=8)

timeout is expressed in seconds. When omitted, the configured framework WAIT_TIME applies.