screenwright 0.1.0b1
A Python Screenplay pattern framework with cinematic test reporting
License: Apache-2.0
Requires Python: >=3.11
Keywords: bdd, pytest, reporting, screenplay, testing

# Screenwright

A Python Screenplay pattern framework with cinematic test reporting.

[![PyPI version](https://img.shields.io/pypi/v/screenwright)](https://pypi.org/project/screenwright/)
[![Python versions](https://img.shields.io/pypi/pyversions/screenwright)](https://pypi.org/project/screenwright/)
[![License](https://img.shields.io/pypi/l/screenwright)](https://github.com/Hossein-Fasihi/screenwright/blob/main/LICENSE)
[![Tests](https://img.shields.io/github/actions/workflow/status/owner/screenwright/ci.yml?label=tests)](https://github.com/Hossein-Fasihi/screenwright/actions)

Screenwright brings the Screenplay pattern to Python testing. Actors perform
Tasks, exercise Abilities through Interactions, and verify outcomes by asking
Questions -- all while generating cinematic HTML reports with Material Design 3
dark neon theming.

## Key Features

- **Screenplay Pattern Engine** -- Actor, Task, Interaction, Question, Ability,
  and Fact primitives with full event sourcing
- **pytest-bdd Integration** -- Auto-registered plugin with Stage and Actor
  fixtures, zero configuration required
- **Cinematic HTML Reports** -- Dashboard overview with summary cards, feature
  lists, and scenario rows; theatre-style scenario presentations with actor
  entrances, ability badges, interaction arrows, and narration subtitles
- **Material Design 3 Theming** -- YAML-based theme configuration with tonal
  palette generation, neon glow effects, and customizable personas
- **Typed Domain Events** -- 17 frozen dataclass events with JSON serialization,
  enabling full traceability of test execution
- **Fully Typed** -- py.typed marker with strict mypy compliance

## Installation

```bash
pip install screenwright
```

For development:

```bash
pip install screenwright[dev]
```

## Quick Start

### 1. Write a feature file

```gherkin
# features/search.feature
Feature: Web Search

  Scenario: Search for a term
    Given Ali can browse the web
    When Ali searches for "Screenplay pattern"
    Then Ali should see results containing "Screenplay"
```

### 2. Define step implementations using the Screenplay pattern

```python
# tests/step_defs/test_search_steps.py
from pytest_bdd import scenario, given, when, then, parsers
from screenwright import Actor, Ability, Interaction, Question, task

# -- Abilities --
class BrowseTheWeb(Ability):
    def __init__(self, driver):
        self.driver = driver

    @staticmethod
    def using(driver):
        return BrowseTheWeb(driver)

# -- Interactions --
class SearchFor(Interaction):
    def __init__(self, term):
        self.term = term

    @staticmethod
    def the_term(term):
        return SearchFor(term)

    def perform_as(self, actor):
        driver = actor.ability_to(BrowseTheWeb).driver
        driver.find_element("name", "q").send_keys(self.term)
        driver.find_element("name", "q").submit()

# -- Questions --
class SearchResults(Question):
    def answered_by(self, actor):
        driver = actor.ability_to(BrowseTheWeb).driver
        return driver.find_element("id", "results").text

# -- Steps --
@scenario("../features/search.feature", "Search for a term")
def test_search():
    pass

@given("Ali can browse the web")
def ali_can_browse(actor, stage):
    ali = stage.actor_named("Ali")
    ali.who_can(BrowseTheWeb.using(create_driver()))

@when(parsers.parse('Ali searches for "{term}"'))
def ali_searches(stage, term):
    ali = stage.shines_spotlight_on("Ali")
    ali.attempts_to(SearchFor.the_term(term))

@then(parsers.parse('Ali should see results containing "{text}"'))
def ali_sees_results(stage, text):
    ali = stage.shines_spotlight_on("Ali")
    ali.should_see_that(SearchResults(), lambda answer: text in answer)
```

### 3. Run tests

```bash
pytest tests/ --screenwright-report=report.html
```

Open `report.html` to view the cinematic test report.

## Documentation

Full documentation is available at [screenwright.dev](https://screenwright.dev).

## License

Screenwright is released under the [Apache License 2.0](LICENSE).