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

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

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

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?

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.

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

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 for project .env, shell, CI and VS Code examples, configuration precedence, and the proposed fixture override.

Repository-only Component identification requirements 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:

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

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.