State-driven web automation framework for complex workflows
Athesa is a protocol-oriented Python framework for building maintainable web automation processes using state machines, screen detection, and declarative action sequences.
- 🎯 State Machine Architecture - Clear workflow definition with explicit state transitions
- 🔍 Smart Screen Detection - Robust page state detection with multiple strategies
- 🔌 Pluggable Adapters - Support for Selenium, Playwright, and custom automation tools
- 📦 Protocol-Oriented - Duck typing with Python protocols, no forced inheritance
- 🎪 Event System - Built-in event emitter
- 🏭 Process Factory - Registry for managing and discovering automation processes
- Testable - Clean separation of concerns, easy to unit test
pip install athesafrom athesa import ProcessRunner, ProcessContext
from athesa.adapters.selenium import SeleniumBridge
from selenium import webdriver
# Setup browser
driver = webdriver.Chrome()
bridge = SeleniumBridge(driver)
# Create context
context = ProcessContext(
credentials={'username': 'user@example.com', 'password': 'secret'}
)
# Run process
from my_processes import LoginProcess
process = LoginProcess()
runner = ProcessRunner(process, context, bridge)
outcome = runner.run()
print(f"Result: {outcome}") # 'success', 'failure', or 'retry'
driver.quit()- Getting Started - Introduction and setup
- API Reference - Complete API documentation
- Quick Reference - Common patterns and snippets
- Examples - Working examples
A complete workflow from start to finish. Defines screens, handlers, states, and transitions.
A step in your workflow. Each state knows what screens to expect.
A detectable page state using selectors and verification criteria.
Actions to perform when a screen is detected.
Abstraction layer for browser automation (Selenium, Playwright, custom).
Problem: Web automation is brittle. Pages change, flows have edge cases, errors are hard to debug.
Solution: Athesa uses explicit state machines and screen detection:
- ✅ Clear state transitions make debugging easy
- ✅ Multiple detection strategies handle dynamic pages
- ✅ Process registry allows flow composition
- ✅ Event system provides observability
- ✅ Protocol-based (no forced inheritance)
┌─────────────────────────────────────────┐
│ Your Process Definition │
│ (States, Screens, Handlers) │
└──────────────┬──────────────────────────┘
│
┌───────▼────────┐
│ ProcessRunner │
└───────┬────────┘
│
┌──────────┼──────────┐
│ │ │
┌───▼───┐ ┌──▼──┐ ┌───▼────┐
│State │ │Page │ │Action │
│Machine│ │Det. │ │Executor│
└───┬───┘ └──┬──┘ └───┬────┘
│ │ │
└─────────┼─────────┘
│
┌─────▼─────┐
│ Bridge │
│ (Selenium)│
└───────────┘
Contributions are welcome! Please read CONTRIBUTING.md first.
MIT License - see LICENSE file
Built with ❤️ for the automation community.
Athesa - Smooth automation flows, state by state.