Metadata-Version: 2.4
Name: robo-automation
Version: 0.1.20
Summary: Reusable Playwright and pytest automation framework utilities
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12,<3.13
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: playwright (==1.63.0)
Requires-Dist: psutil (==7.2.2)
Requires-Dist: pytest (==9.1.1)
Description-Content-Type: text/markdown

# 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:

```text
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:

```text
consumer fixture override
        ↓
environment variable
        ↓
library default
```

Example: if the consumer sets:

```text
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:

```text
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`:

```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](https://dinilmithra.github.io/robo-automation-docs/browser-visibility/)
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:

```powershell
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](COMPILED_WHEELS.md) 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](technical-documentation/README.md).

## 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.

