Metadata-Version: 2.4
Name: pytest-template
Version: 0.1.0
Summary: Simple pytest helper to assert HTML elements with CSS selectors
Author: Caio Hamamura
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: beautifulsoup4
Requires-Dist: lxml

# 📦 pytest-template
**Simple pytest helpers for asserting HTML elements using CSS selectors.**  
Designed for Django testing, HTMX responses, and plain HTML strings.

---

## ✨ Features

- Assert the existence of HTML elements with a CSS selector  
- Works with **Django TestClient responses** or **raw HTML**  
- Optional check for **number of matching elements**  
- Uses BeautifulSoup + lxml internally  
- Zero dependencies on Django inside the library — fully optional  
- Tiny, fast, easy to use

---

## 📥 Installation

Install the package normally:

```bash
pip install pytest-template
```

Or for development with tests:

```bash
pip install -e .[test]
```

---

## 🔧 Core API

### `assertElement(html_or_response, selector, expected_count=None)`

| Argument | Type | Description |
|---------|------|-------------|
| `html_or_response` | Django response, bytes, or string | The HTML to inspect |
| `selector` | str | CSS selector to search |
| `expected_count` | int (optional) | Require an exact number of matches |

---

## 🧪 Usage Examples

### ✔ Django Test Example

```python
from django.test import Client
from pytest_template import assertElement

def test_homepage():
    client = Client()
    res = client.get("/")

    # Assert existence of the element
    assertElement(res, "h1")

    # Assert exactly 3 list items
    assertElement(res, "ul li", 3)

    # Validate that navbar exists
    assertElement(res, "nav.navbar")
```

### ✔ Raw HTML Example

```python
from pytest_template import assertElement

def test_simple_html():
    html = """
    <div>
        <p class="msg">Hello</p>
        <span class="msg">World</span>
    </div>
    """

    assertElement(html, ".msg", 2)
```

---

## 🧩 Why this library exists

Django’s built-in test utilities are powerful, but:

- They do **not** provide a concise CSS selector assertion  
- `assertContains()` only checks text, not elements  
- HTML parsing in tests becomes repetitive and verbose  

This package gives you a single clean line:

```python
assertElement(res, ".card-title")
```

Instead of manually writing BeautifulSoup logic.

---

## 📚 Full Example Test

```python
def test_blog_list(client):
    res = client.get("/blog/")

    # List container
    assertElement(res, "#post-list", 1)

    # Each post has title and content
    assertElement(res, ".post .title")
    assertElement(res, ".post .content")
```

---

## 🧰 Running the test suite

This project uses `pytest` and optionally `pytest-django`.

Install test dependencies:

```bash
pip install -e .[test]
```

Run tests:

```bash
pytest -q
```

If Django or pytest-django are not installed, Django-specific tests will be skipped automatically.

---

## 📝 License

MIT License — free to use for personal and commercial projects.
