Metadata-Version: 2.4
Name: robo-appian
Version: 0.1.37
Summary: Reusable automation components for Appian applications.
License-Expression: MIT
License-File: LICENSE
Author: Dinil Mithra
Maintainer: Dinil Mithra
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: pytest (==9.1.1)
Requires-Dist: robo-automation (==0.1.20)
Project-URL: Documentation, https://dinilmithra.github.io/robo-appian-docs/
Project-URL: Developer, https://www.linkedin.com/in/dinilmithra/
Project-URL: Issues, https://github.com/dinilmithra/robo-appian/issues
Project-URL: Repository, https://github.com/dinilmithra/robo-appian
Description-Content-Type: text/markdown

# robo-appian

`robo-appian` (robo appian / `robo_appian`) by Dinil Mithra makes Appian pages easier to automate with readable Python. It is a Python automation and testing library for Appian applications.

It is designed for people who know their web application and only need basic Python to start writing automation.

## Quick example

```python
from robo_appian import AppianPage


def test_update_item(page: AppianPage) -> None:
    page.textbox(label="Description").fill("Example item")
    page.date(label="Start Date").fill("10/15/2026")
    page.radio(label="Priority").select("High")
    page.button(name="Submit").click()
```

The goal is to describe the page using the same text a user sees.

## Install

```bash
pip install robo-appian
python -m playwright install firefox
```

Python 3.12 is required. `robo-appian` uses `robo-automation` for generic browser and pytest infrastructure.

## Common controls

```python
page.textbox(label="Description").fill("Example item")
page.textbox(placeholder="example@example.com").fill("user@example.com")
page.textbox("Employee").select(search_text="John", value="John Smith")
page.date(label="Start Date").fill("10/15/2026")
page.radio(label="Priority").select("High")
page.button(name="Next").click()
```

Textboxes, dates, and selection components automatically move focus out after a value changes so Appian can process it.

## What belongs where?

```text
Your application tests
        ↓
robo-appian       Appian controls and Appian behavior
        ↓
robo-automation   Browser and pytest infrastructure
        ↓
Playwright
```

Your application project should own application URLs, login policy, business workflows, assertions, and test data.

## Documentation

Start with the beginner guides:

- Installation
- Quick Start
- Your First Test
- Choosing a Component
- Troubleshooting

Advanced architecture and pytest integration are documented separately for framework maintainers.

Full documentation:

**https://dinilmithra.github.io/robo-appian-docs/**

## License

`robo-appian` is licensed under the [MIT License](LICENSE).
## Error handling

Appian-specific library failures use `RoboAppianError`, which is also a `RoboAutomationError`. Normal tests should usually let pytest report these errors. If you need recovery or diagnostic handling, see **[How to use RoboAppianError](https://dinilmithra.github.io/robo-appian-docs/getting-started/error-handling/)** for examples using `code`, `details`, `to_dict()`, and exception chaining.


## Runtime boundary for application projects

Application projects should normally import automation APIs only from
`robo_appian`.

```python
from robo_appian import AppianPage, AppianRuntime, RoboAppianError
```

`AppianRuntime` provides the Appian-facing browser/session lifecycle used by
advanced consumer fixtures. It intentionally hides lower browser and
performance implementation classes. Normal test authors usually only need the
`page` fixture and component APIs shown above.

## Automation authoring

Use the component APIs directly to build application-specific automation suites.
Recording, step review, test generation and Testcase Studio are supplied by a
separate optional authoring library. Generated tests use the same public Appian
components and runtime; installing the authoring UI is not required to run them.

### Exact keyed grid rows

`grid.row_matching(column_name="Vendor #", value="549")` returns a live row
matched by normalized exact text in the named column. With its default `wait=True`,
it requires one matching grid and one matching row; duplicates fail rather than
selecting the first match. `timeout`, tri-state `visible`, and `wait=False` are
available. Existing positional/named row, column, cell and counting APIs are
unchanged. This lookup only searches rendered rows and does not paginate.

Use `grid.row(name=..., exact=True, unique=True)` to require a unique named row.
One-based row and column numbers are also supported. Numbered rows are positional
and do not remain bound to the same record after sorting or filtering.

### Dialog-scoped fields

`AppianDialog` now exposes `textbox(...)`, `date(...)` and `grid(...)` using the
existing component constructors with dialog scope. `dialog.grid(..., wait=False)`
supports optional lookup; default grid/row/cell/component synchronization remains
in place. Grid cell actions retain the original AppianPage as their owner.
## Headless execution

Pytest browsers default to visible (`HEAD_LESS=N`) in this workspace. Use
`HEAD_LESS=Y` for headless execution. See the [Headless execution guide](https://dinilmithra.github.io/robo-appian-docs/guides/headless-execution/)
for project `.env`, shell, CI and VS Code examples, configuration precedence, and
the proposed fixture override.

Repository-only [Component identification requirements](technical-requirements/component-identification.md)
describe how RoboAppian recognizes buttons and other components. This technical
reference is kept outside the GitHub Pages documentation source.

## Setup help

From the project directory:

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

Options include `--browser {all,chromium,firefox,webkit}`, `--with-docs`,
`--bootstrap-poetry`, and `--bootstrap-timeout` (30 seconds by default).
Help lists supported choices and defaults without creating an environment or
installing packages. Unknown options are rejected before setup begins.

## 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-appian-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-appian-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.
Supply `--bootstrap-poetry` if the pinned Poetry tool is not installed.

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

