snakeoil-web 0.1.23

Plain English web test automation using Selenium and Playwright. No code. No maintenance.

snakeoil-web

Dependencies

• Python 3.8+
• A supported browser installed on your machine (Chrome, Firefox, Safari, or Edge)

Everything else — Playwright, pytest, pytest-html — is installed automatically by snakeoil init.

---

Install

pip install snakeoil-web

---

Quick start

pip install snakeoil-web
snakeoil init
pytest web-tests/

snakeoil init creates your project structure, installs pytest and pytest-html, installs browser binaries, and generates sample tests ready to run.

---

What snakeoil init creates

your-project/
├── snakeoil.web.config.py   ← configure URL, browser, headless mode
├── conftest.py              ← pytest fixture (browser session per test)
├── pytest.ini               ← pytest settings
└── web-tests/
    ├── test_english.py      ← English instruction style tests
    └── test_pythonic.py     ← Pythonic API style tests

After running your tests:

your-project/
└── report.html              ← test report (open in browser)

---

Configuration

Edit snakeoil.web.config.py in your project root to point at your site and set your preferences:

# URL of the site under test
URL = "https://yourapp.com"

# Browser to use: chrome | firefox | safari | edge
# chrome  — Google Chrome (must be installed)
# firefox — Mozilla Firefox (must be installed)
# safari  — Safari via WebKit (macOS only)
# edge    — Microsoft Edge (must be installed)
BROWSER = "chrome"

# Run browser without a visible window (True for CI, False for local debugging)
HEADLESS = False

# Launch browser maximized (ignored when HEADLESS = True)
MAXIMIZED = True

# Maximum time in milliseconds to wait for elements and page loads
TIMEOUT = 30_000

# Directory where report.html is saved after each test run
RESULT_DIR = "."

---

Two ways to write tests

English — human readable, shareable with non-developers:

def test_login(agent):
    agent.run([
        'type "[e-mail]" into "Email"',
        'type "secret123" into "Password"',
        'click "Sign in"',
        'verify text "Dashboard" is present',
    ])

Pythonic — IDE guided, autocomplete friendly:

def test_login(agent):
    (agent
        .type("[e-mail]", into="Email")
        .type("secret123", into="Password")
        .click("Sign in")
        .verify_text("Dashboard")
    )

---

Supported instructions

Actions

Instruction	Example
Type into a field	type "value" into "Field Label"
Click an element	click "Button Text"
Click by position	click "Add to cart" below "Product Name"
Click near element	click "Edit" near "John Smith"
Click nth element	click second "Add to cart"
Select a dropdown	select "Option" from "dropdown_name"
Hover over element	hover "element"
Press a key	press Enter
Navigate to URL	navigate "https://yourapp.com/page"

Verification

Instruction	Example
Verify text is present	verify text "Welcome" is present
Verify element is present	verify "Submit" is present
Verify element is visible	verify "Submit" is visible
Verify text next to element	verify text next to "Balance" is "$100.00"
Verify text below element	verify text below "Total" is "$29.99"

Extraction

Instruction	Example
Extract from element	extract text from "element_class"
Extract nth	extract text from first "item name"
Extract next to element	extract text next to "Balance"
Extract near element	extract text near "Balance"
Extract below element	extract text below "Label"
Extract above element	extract text above "Label"
Capture into variable	{{price}} = extract text next to "Total"

---

Spatial targeting

Use element position when there's no unique visible text:

# Pythonic
agent.click("Add to cart", below="Sauce Labs Backpack")
agent.click("Edit", next_to="John Smith")
agent.extract_text(next_to="Balance")

# English
agent.run('click "Add to cart" below "Sauce Labs Backpack"')
agent.run('extract text next to "Balance"')

Supported directions: next to, below, above, left of, right of, near

---

Extracting values

# Direct return
price = agent.run('extract text next to "Total"')
assert price == "$29.99"

# Variable capture inside run()
agent.run('{{balance}} = extract text next to "Balance"')
balance = agent.get("balance")

# Pythonic
price = agent.extract_text(next_to="Total")

---

Using variables in tests

username = "standard_user"
password = "secret_sauce"

def test_login(agent):
    agent.run([
        f'type "{username}" into "Username"',   # f-strings for Python variables
        f'type "{password}" into "Password"',
        'click "Login"',
        'verify text "Products" is present',
    ])

---

Running tests

# Run all tests
pytest web-tests/

# Run a single test
pytest web-tests/test_english.py::test_login

# Run headless (no browser window)
HEADLESS=True pytest web-tests/

# View the report
open report.html

---

Supported browsers

Config value	Browser
chrome	Google Chrome
firefox	Mozilla Firefox
safari	Safari (macOS only)
edge	Microsoft Edge

Chrome, Firefox, and Edge must be installed on your machine. Safari is available on macOS without additional installation.

PyPI