Metadata-Version: 2.4
Name: snakeoil-web
Version: 0.1.33
Summary: Plain English web test automation using Selenium and Playwright. No code. No maintenance.
License: MIT
Project-URL: Homepage, https://github.com/snakeoiltool/snakeoil-web
Keywords: testing,automation,plain-english,selenium,playwright,web
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: playwright>=1.40.0
Requires-Dist: pytest>=7.0.0

# snakeoil-web

[![PyPI version](https://badge.fury.io/py/snakeoil-web.svg)](https://pypi.org/project/snakeoil-web/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install snakeoil-web
```

---

## Quick start

```bash
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
├── 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:

```python
# 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 = "test_report"

# Capture a screenshot when a step fails and embed it in the report
SCREENSHOTS_ON_FAILURE = False
```

---

## Two ways to write tests

**English — human readable, shareable with non-developers:**
```python
def test_login(agent):
    agent.run([
        'type "harish@example.com" into "Email"',
        'type "secret123" into "Password"',
        'click "Sign in"',
        'verify text "Dashboard" is present',
    ])
```

**Pythonic — IDE guided, autocomplete friendly:**
```python
def test_login(agent):
    (agent
        .type("harish@example.com", 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:

```python
# 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

```python
# 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

```python
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

```bash
# 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](https://pypi.org/project/snakeoil-web/)
