robo-automation

robo-automation provides shared browser and pytest infrastructure for automation projects.

Most application test developers do not need to call its internal services directly. Higher-level libraries such as robo-appian use it automatically.

What it provides

• browser and page lifecycle;
• pytest fixtures;
• configurable wait time;
• logging and correlation;
• diagnostics and artifacts;
• performance monitoring;
• reusable RoboPage and RoboLocator wrappers.

It intentionally contains no application-specific business logic.

Basic pytest use

When installed as a pytest plugin, the library can provide browser/page infrastructure automatically.

A higher-level library may replace the public page type while keeping the same browser lifecycle. For example:

application test
      ↓
robo-appian AppianPage
      ↓
robo-automation browser lifecycle
      ↓
Playwright

Configuration

Consumers can use the library without defining any configuration. Defaults are built in.

When a setting needs to change, precedence is:

consumer fixture override
        ↓
environment variable
        ↓
library default

Example: if the consumer sets:

PYTEST_LOG_LEVEL=ERROR

and does not override the logging fixture, the effective log level is ERROR.

Common public fixtures

Important configuration/runtime fixtures include:

robo_runtime_config
robo_logging_config
robo_diagnostics_config
robo_performance_config
robo_artifact_paths
wait_time
browser
context
robo_page

Application projects should override policy/configuration fixtures rather than reimplementing generic browser lifecycle.

Layering rule

robo-automation should contain a feature only when it is application-independent.

• Generic browser/logging/diagnostics/performance → robo-automation
• Appian behavior → robo-appian
• Application workflow/login/business rules → consumer project

Advanced documentation

Framework maintainers can continue with the Architecture, Runtime Configuration, Performance and API guides on the public documentation site.

Error handling

Consumer code can catch RoboAutomationError when it has a real recovery path. Normal pytest tests should usually let the exception propagate so reports keep the full failure evidence. See https://dinilmithra.github.io/robo-automation-docs/getting-started/error-handling/.

Browser lifetime

The default robo_browser_scope = session keeps one browser and automation runtime per pytest worker. Applications that need a completely fresh browser process for each testcase can set this in pytest.ini:

[pytest]
robo_browser_scope = function

Both browser and automation-driver fixtures then close after every testcase. Contexts and pages remain scoped to each test. The Appian runtime fixture follows the same setting. Application logout should run in the page fixture finalizer, before the underlying browser resources close.

Browser visibility default

When HEAD_LESS is unset, browsers launch visibly (HEAD_LESS=N). Set HEAD_LESS=Y explicitly for headless execution. Existing environment values continue to override the default. Browser lifecycle and cleanup are unchanged.

See Browser visibility and fixture override recommendation for current .env/environment precedence and the proposed public headless fixture. The fixture override is a design recommendation, not an implemented API.

Setup help

From the project directory:

py -3.12 .\tools\setup.py --help

This setup supports -h and --help; it has no additional command-line options. Help lists supported choices and defaults without creating an environment or installing packages. Unknown options are rejected before setup begins.

Poetry ownership

Setup asks Poetry to create or reuse the project environment and runs Poetry lock/check/install for project dependencies. Existing environments are preserved. Pip is used only to bootstrap the pinned Poetry tool; project libraries are managed through the manifest and lockfile.

Compiled distribution (maintainers)

Use python scripts/github/build_compiled_wheel.py --plan to review the protection inventory and python scripts/github/build_compiled_wheel.py to build an audited native wheel. See compiled distributions for requirements, platform builds, readable entry-point exceptions and release instructions.

Documentation

User documentation and homepage assets are maintained in the separate public robo-automation-docs repository. This private project contains the library source. The public repository owns its Poetry documentation environment and Pages workflow. No documentation deployment token is required in this private repository.

Documentation site: https://dinilmithra.github.io/robo-automation-docs/ .

Internal documentation: technical-documentation.

Repository environment setup

From this repository, run python tools/setup.py --help to see every supported option, then python tools/setup.py with Python 3.12. Setup uses Poetry 2.5.1 and preserves the existing repository-specific installation and validation steps.

Setup security updates

Run python tools/setup.py with Python 3.12 to secure the project environment. Setup verifies pip is at least 26.2.2, upgrading older pip through the official SHA256-pinned wheel before downloading Poetry. Newer stable pip is preserved. Poetry 2.5.1 tooling requires certifi>=2026.10.19. Existing external Poetry tools with an outdated CA bundle are not used or modified; setup creates a secure bootstrap environment where allowed. Appian setup needs --bootstrap-poetry when no secure external Poetry installation is available.

Project dependencies and lockfiles stay under Poetry management. If certifi is already locked below the security minimum, setup updates that lock through Poetry and stops if the project constraints cannot resolve a safe version. A project without certifi in its lockfile does not need to add it solely for the Poetry tool. Downloads or verification failures stop setup before it reports success.

Standalone setup

Environment creation, secure tooling bootstrap and Poetry validation are included in the project setup implementation. Run python tools/setup.py --help; a separate environment helper module is not required. Project setup options and existing environment names are preserved.