Skip to content

Events API

screenwright.events

Event definitions -- Shared Kernel.

AbilityGranted dataclass

Bases: Event

An Ability has been granted to an Actor.

Source code in src/screenwright/events/screenplay.py 
37
38
39
40
41
42
43
44
@dataclass(frozen=True)
class AbilityGranted(Event):
    """An Ability has been granted to an Actor."""

    event_type: ClassVar[str] = "ability_granted"
    actor_name: str = ""
    ability_name: str = ""
    ability_type: str = ""

ActorEnteredStage dataclass

Bases: Event

An Actor has been placed on the Stage.

Source code in src/screenwright/events/screenplay.py 
11
12
13
14
15
16
17
@dataclass(frozen=True)
class ActorEnteredStage(Event):
    """An Actor has been placed on the Stage."""

    event_type: ClassVar[str] = "actor_entered_stage"
    actor_name: str = ""
    description: str | None = None

ActorExitedStage dataclass

Bases: Event

An Actor has been cleaned up at Scene end.

Source code in src/screenwright/events/screenplay.py 
20
21
22
23
24
25
@dataclass(frozen=True)
class ActorExitedStage(Event):
    """An Actor has been cleaned up at Scene end."""

    event_type: ClassVar[str] = "actor_exited_stage"
    actor_name: str = ""

Event dataclass

Base class for all domain events.

Every event is immutable (frozen dataclass), has a unique ID, and a UTC timestamp. The event_type class variable is a string identifier used for serialization dispatch.

Source code in src/screenwright/events/base.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
@dataclass(frozen=True)
class Event:
    """Base class for all domain events.

    Every event is immutable (frozen dataclass), has a unique ID,
    and a UTC timestamp. The event_type class variable is a string
    identifier used for serialization dispatch.
    """

    event_id: str = field(default_factory=lambda: str(uuid.uuid4()))
    timestamp: datetime.datetime = field(
        default_factory=lambda: datetime.datetime.now(datetime.UTC)
    )

    event_type: ClassVar[str] = "event"

    def to_dict(self) -> dict[str, object]:
        """Serialize this event to a dictionary.

        Returns:
            A dict with all fields, including event_type from the class.
        """
        from dataclasses import fields as dc_fields

        result: dict[str, object] = {"event_type": type(self).event_type}
        for f in dc_fields(self):
            value = getattr(self, f.name)
            if isinstance(value, datetime.datetime):
                result[f.name] = value.isoformat()
            elif isinstance(value, list):
                result[f.name] = list(value)
            else:
                result[f.name] = value
        return result

to_dict()

Serialize this event to a dictionary.

Returns:

Type Description
dict[str, object]

A dict with all fields, including event_type from the class.
Source code in src/screenwright/events/base.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def to_dict(self) -> dict[str, object]:
    """Serialize this event to a dictionary.

    Returns:
        A dict with all fields, including event_type from the class.
    """
    from dataclasses import fields as dc_fields

    result: dict[str, object] = {"event_type": type(self).event_type}
    for f in dc_fields(self):
        value = getattr(self, f.name)
        if isinstance(value, datetime.datetime):
            result[f.name] = value.isoformat()
        elif isinstance(value, list):
            result[f.name] = list(value)
        else:
            result[f.name] = value
    return result

FactRemembered dataclass

Bases: Event

A Fact has been stored by an Actor.

Source code in src/screenwright/events/screenplay.py 
47
48
49
50
51
52
53
54
@dataclass(frozen=True)
class FactRemembered(Event):
    """A Fact has been stored by an Actor."""

    event_type: ClassVar[str] = "fact_remembered"
    actor_name: str = ""
    fact_key: str = ""
    fact_value_summary: str = ""

FeatureEnded dataclass

Bases: Event

A BDD Feature file has completed execution.

Source code in src/screenwright/events/bdd.py 
20
21
22
23
24
25
26
27
28
29
30
@dataclass(frozen=True)
class FeatureEnded(Event):
    """A BDD Feature file has completed execution."""

    event_type: ClassVar[str] = "feature_ended"
    feature_name: str = ""
    total_scenarios: int = 0
    passed: int = 0
    failed: int = 0
    skipped: int = 0
    duration_ms: float = 0.0

FeatureStarted dataclass

Bases: Event

A BDD Feature file has begun execution.

Source code in src/screenwright/events/bdd.py 
11
12
13
14
15
16
17
@dataclass(frozen=True)
class FeatureStarted(Event):
    """A BDD Feature file has begun execution."""

    event_type: ClassVar[str] = "feature_started"
    feature_name: str = ""
    feature_path: str = ""

InteractionCompleted dataclass

Bases: Event

An Interaction has completed successfully.

Source code in src/screenwright/events/screenplay.py 
100
101
102
103
104
105
106
107
@dataclass(frozen=True)
class InteractionCompleted(Event):
    """An Interaction has completed successfully."""

    event_type: ClassVar[str] = "interaction_completed"
    actor_name: str = ""
    interaction_name: str = ""
    duration_ms: float = 0.0

InteractionFailed dataclass

Bases: Event

An Interaction has failed with an error.

Source code in src/screenwright/events/screenplay.py 
110
111
112
113
114
115
116
117
118
119
@dataclass(frozen=True)
class InteractionFailed(Event):
    """An Interaction has failed with an error."""

    event_type: ClassVar[str] = "interaction_failed"
    actor_name: str = ""
    interaction_name: str = ""
    error_type: str = ""
    error_message: str = ""
    duration_ms: float = 0.0

InteractionStarted dataclass

Bases: Event

An Actor has begun executing an Interaction.

Source code in src/screenwright/events/screenplay.py 
89
90
91
92
93
94
95
96
97
@dataclass(frozen=True)
class InteractionStarted(Event):
    """An Actor has begun executing an Interaction."""

    event_type: ClassVar[str] = "interaction_started"
    actor_name: str = ""
    interaction_name: str = ""
    target: str | None = None
    parent_id: str | None = None

Outcome

Bases: StrEnum

Possible outcomes for a scenario or step.

Source code in src/screenwright/events/base.py 
12
13
14
15
16
17
18
class Outcome(StrEnum):
    """Possible outcomes for a scenario or step."""

    PASSED = "passed"
    FAILED = "failed"
    SKIPPED = "skipped"
    ERROR = "error"

QuestionAnswered dataclass

Bases: Event

A Question has been answered with a value.

Source code in src/screenwright/events/screenplay.py 
132
133
134
135
136
137
138
139
140
@dataclass(frozen=True)
class QuestionAnswered(Event):
    """A Question has been answered with a value."""

    event_type: ClassVar[str] = "question_answered"
    actor_name: str = ""
    question_name: str = ""
    answer_summary: str = ""
    duration_ms: float = 0.0

QuestionAsked dataclass

Bases: Event

An Actor has asked a Question.

Source code in src/screenwright/events/screenplay.py 
122
123
124
125
126
127
128
129
@dataclass(frozen=True)
class QuestionAsked(Event):
    """An Actor has asked a Question."""

    event_type: ClassVar[str] = "question_asked"
    actor_name: str = ""
    question_name: str = ""
    parent_id: str | None = None

SceneEnded dataclass

Bases: Event

A BDD Scenario (Scene) has completed execution.

Source code in src/screenwright/events/bdd.py 
43
44
45
46
47
48
49
50
51
52
53
@dataclass(frozen=True)
class SceneEnded(Event):
    """A BDD Scenario (Scene) has completed execution."""

    event_type: ClassVar[str] = "scene_ended"
    scene_name: str = ""
    feature_name: str = ""
    outcome: str = ""
    duration_ms: float = 0.0
    error_type: str | None = None
    error_message: str | None = None

SceneStarted dataclass

Bases: Event

A BDD Scenario (Scene) has begun execution.

Source code in src/screenwright/events/bdd.py 
33
34
35
36
37
38
39
40
@dataclass(frozen=True)
class SceneStarted(Event):
    """A BDD Scenario (Scene) has begun execution."""

    event_type: ClassVar[str] = "scene_started"
    scene_name: str = ""
    feature_name: str = ""
    tags: list[str] = field(default_factory=list)

SpotlightChanged dataclass

Bases: Event

The Spotlight has shifted to a different Actor.

Source code in src/screenwright/events/screenplay.py 
28
29
30
31
32
33
34
@dataclass(frozen=True)
class SpotlightChanged(Event):
    """The Spotlight has shifted to a different Actor."""

    event_type: ClassVar[str] = "spotlight_changed"
    previous_actor: str | None = None
    current_actor: str = ""

TaskCompleted dataclass

Bases: Event

An Actor has finished performing a Task successfully.

Source code in src/screenwright/events/screenplay.py 
67
68
69
70
71
72
73
74
@dataclass(frozen=True)
class TaskCompleted(Event):
    """An Actor has finished performing a Task successfully."""

    event_type: ClassVar[str] = "task_completed"
    actor_name: str = ""
    task_name: str = ""
    duration_ms: float = 0.0

TaskFailed dataclass

Bases: Event

A Task has failed with an error.

Source code in src/screenwright/events/screenplay.py 
77
78
79
80
81
82
83
84
85
86
@dataclass(frozen=True)
class TaskFailed(Event):
    """A Task has failed with an error."""

    event_type: ClassVar[str] = "task_failed"
    actor_name: str = ""
    task_name: str = ""
    error_type: str = ""
    error_message: str = ""
    duration_ms: float = 0.0

TaskStarted dataclass

Bases: Event

An Actor has begun performing a Task.

Source code in src/screenwright/events/screenplay.py 
57
58
59
60
61
62
63
64
@dataclass(frozen=True)
class TaskStarted(Event):
    """An Actor has begun performing a Task."""

    event_type: ClassVar[str] = "task_started"
    actor_name: str = ""
    task_name: str = ""
    parent_id: str | None = None

base

Base Event class and Outcome enum for domain events.

Event dataclass

Base class for all domain events.

Every event is immutable (frozen dataclass), has a unique ID, and a UTC timestamp. The event_type class variable is a string identifier used for serialization dispatch.

Source code in src/screenwright/events/base.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
@dataclass(frozen=True)
class Event:
    """Base class for all domain events.

    Every event is immutable (frozen dataclass), has a unique ID,
    and a UTC timestamp. The event_type class variable is a string
    identifier used for serialization dispatch.
    """

    event_id: str = field(default_factory=lambda: str(uuid.uuid4()))
    timestamp: datetime.datetime = field(
        default_factory=lambda: datetime.datetime.now(datetime.UTC)
    )

    event_type: ClassVar[str] = "event"

    def to_dict(self) -> dict[str, object]:
        """Serialize this event to a dictionary.

        Returns:
            A dict with all fields, including event_type from the class.
        """
        from dataclasses import fields as dc_fields

        result: dict[str, object] = {"event_type": type(self).event_type}
        for f in dc_fields(self):
            value = getattr(self, f.name)
            if isinstance(value, datetime.datetime):
                result[f.name] = value.isoformat()
            elif isinstance(value, list):
                result[f.name] = list(value)
            else:
                result[f.name] = value
        return result
to_dict()

Serialize this event to a dictionary.

Returns:

Type Description
dict[str, object]

A dict with all fields, including event_type from the class.
Source code in src/screenwright/events/base.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def to_dict(self) -> dict[str, object]:
    """Serialize this event to a dictionary.

    Returns:
        A dict with all fields, including event_type from the class.
    """
    from dataclasses import fields as dc_fields

    result: dict[str, object] = {"event_type": type(self).event_type}
    for f in dc_fields(self):
        value = getattr(self, f.name)
        if isinstance(value, datetime.datetime):
            result[f.name] = value.isoformat()
        elif isinstance(value, list):
            result[f.name] = list(value)
        else:
            result[f.name] = value
    return result

Outcome

Bases: StrEnum

Possible outcomes for a scenario or step.

Source code in src/screenwright/events/base.py 
12
13
14
15
16
17
18
class Outcome(StrEnum):
    """Possible outcomes for a scenario or step."""

    PASSED = "passed"
    FAILED = "failed"
    SKIPPED = "skipped"
    ERROR = "error"

bdd

BDD Integration events -- emitted during feature and scenario lifecycle.

FeatureEnded dataclass

Bases: Event

A BDD Feature file has completed execution.

Source code in src/screenwright/events/bdd.py 
20
21
22
23
24
25
26
27
28
29
30
@dataclass(frozen=True)
class FeatureEnded(Event):
    """A BDD Feature file has completed execution."""

    event_type: ClassVar[str] = "feature_ended"
    feature_name: str = ""
    total_scenarios: int = 0
    passed: int = 0
    failed: int = 0
    skipped: int = 0
    duration_ms: float = 0.0

FeatureStarted dataclass

Bases: Event

A BDD Feature file has begun execution.

Source code in src/screenwright/events/bdd.py 
11
12
13
14
15
16
17
@dataclass(frozen=True)
class FeatureStarted(Event):
    """A BDD Feature file has begun execution."""

    event_type: ClassVar[str] = "feature_started"
    feature_name: str = ""
    feature_path: str = ""

SceneEnded dataclass

Bases: Event

A BDD Scenario (Scene) has completed execution.

Source code in src/screenwright/events/bdd.py 
43
44
45
46
47
48
49
50
51
52
53
@dataclass(frozen=True)
class SceneEnded(Event):
    """A BDD Scenario (Scene) has completed execution."""

    event_type: ClassVar[str] = "scene_ended"
    scene_name: str = ""
    feature_name: str = ""
    outcome: str = ""
    duration_ms: float = 0.0
    error_type: str | None = None
    error_message: str | None = None

SceneStarted dataclass

Bases: Event

A BDD Scenario (Scene) has begun execution.

Source code in src/screenwright/events/bdd.py 
33
34
35
36
37
38
39
40
@dataclass(frozen=True)
class SceneStarted(Event):
    """A BDD Scenario (Scene) has begun execution."""

    event_type: ClassVar[str] = "scene_started"
    scene_name: str = ""
    feature_name: str = ""
    tags: list[str] = field(default_factory=list)

screenplay

Screenplay Engine events -- emitted by the core domain during test execution.

AbilityGranted dataclass

Bases: Event

An Ability has been granted to an Actor.

Source code in src/screenwright/events/screenplay.py 
37
38
39
40
41
42
43
44
@dataclass(frozen=True)
class AbilityGranted(Event):
    """An Ability has been granted to an Actor."""

    event_type: ClassVar[str] = "ability_granted"
    actor_name: str = ""
    ability_name: str = ""
    ability_type: str = ""

ActorEnteredStage dataclass

Bases: Event

An Actor has been placed on the Stage.

Source code in src/screenwright/events/screenplay.py 
11
12
13
14
15
16
17
@dataclass(frozen=True)
class ActorEnteredStage(Event):
    """An Actor has been placed on the Stage."""

    event_type: ClassVar[str] = "actor_entered_stage"
    actor_name: str = ""
    description: str | None = None

ActorExitedStage dataclass

Bases: Event

An Actor has been cleaned up at Scene end.

Source code in src/screenwright/events/screenplay.py 
20
21
22
23
24
25
@dataclass(frozen=True)
class ActorExitedStage(Event):
    """An Actor has been cleaned up at Scene end."""

    event_type: ClassVar[str] = "actor_exited_stage"
    actor_name: str = ""

FactRemembered dataclass

Bases: Event

A Fact has been stored by an Actor.

Source code in src/screenwright/events/screenplay.py 
47
48
49
50
51
52
53
54
@dataclass(frozen=True)
class FactRemembered(Event):
    """A Fact has been stored by an Actor."""

    event_type: ClassVar[str] = "fact_remembered"
    actor_name: str = ""
    fact_key: str = ""
    fact_value_summary: str = ""

InteractionCompleted dataclass

Bases: Event

An Interaction has completed successfully.

Source code in src/screenwright/events/screenplay.py 
100
101
102
103
104
105
106
107
@dataclass(frozen=True)
class InteractionCompleted(Event):
    """An Interaction has completed successfully."""

    event_type: ClassVar[str] = "interaction_completed"
    actor_name: str = ""
    interaction_name: str = ""
    duration_ms: float = 0.0

InteractionFailed dataclass

Bases: Event

An Interaction has failed with an error.

Source code in src/screenwright/events/screenplay.py 
110
111
112
113
114
115
116
117
118
119
@dataclass(frozen=True)
class InteractionFailed(Event):
    """An Interaction has failed with an error."""

    event_type: ClassVar[str] = "interaction_failed"
    actor_name: str = ""
    interaction_name: str = ""
    error_type: str = ""
    error_message: str = ""
    duration_ms: float = 0.0

InteractionStarted dataclass

Bases: Event

An Actor has begun executing an Interaction.

Source code in src/screenwright/events/screenplay.py 
89
90
91
92
93
94
95
96
97
@dataclass(frozen=True)
class InteractionStarted(Event):
    """An Actor has begun executing an Interaction."""

    event_type: ClassVar[str] = "interaction_started"
    actor_name: str = ""
    interaction_name: str = ""
    target: str | None = None
    parent_id: str | None = None

QuestionAnswered dataclass

Bases: Event

A Question has been answered with a value.

Source code in src/screenwright/events/screenplay.py 
132
133
134
135
136
137
138
139
140
@dataclass(frozen=True)
class QuestionAnswered(Event):
    """A Question has been answered with a value."""

    event_type: ClassVar[str] = "question_answered"
    actor_name: str = ""
    question_name: str = ""
    answer_summary: str = ""
    duration_ms: float = 0.0

QuestionAsked dataclass

Bases: Event

An Actor has asked a Question.

Source code in src/screenwright/events/screenplay.py 
122
123
124
125
126
127
128
129
@dataclass(frozen=True)
class QuestionAsked(Event):
    """An Actor has asked a Question."""

    event_type: ClassVar[str] = "question_asked"
    actor_name: str = ""
    question_name: str = ""
    parent_id: str | None = None

SpotlightChanged dataclass

Bases: Event

The Spotlight has shifted to a different Actor.

Source code in src/screenwright/events/screenplay.py 
28
29
30
31
32
33
34
@dataclass(frozen=True)
class SpotlightChanged(Event):
    """The Spotlight has shifted to a different Actor."""

    event_type: ClassVar[str] = "spotlight_changed"
    previous_actor: str | None = None
    current_actor: str = ""

TaskCompleted dataclass

Bases: Event

An Actor has finished performing a Task successfully.

Source code in src/screenwright/events/screenplay.py 
67
68
69
70
71
72
73
74
@dataclass(frozen=True)
class TaskCompleted(Event):
    """An Actor has finished performing a Task successfully."""

    event_type: ClassVar[str] = "task_completed"
    actor_name: str = ""
    task_name: str = ""
    duration_ms: float = 0.0

TaskFailed dataclass

Bases: Event

A Task has failed with an error.

Source code in src/screenwright/events/screenplay.py 
77
78
79
80
81
82
83
84
85
86
@dataclass(frozen=True)
class TaskFailed(Event):
    """A Task has failed with an error."""

    event_type: ClassVar[str] = "task_failed"
    actor_name: str = ""
    task_name: str = ""
    error_type: str = ""
    error_message: str = ""
    duration_ms: float = 0.0

TaskStarted dataclass

Bases: Event

An Actor has begun performing a Task.

Source code in src/screenwright/events/screenplay.py 
57
58
59
60
61
62
63
64
@dataclass(frozen=True)
class TaskStarted(Event):
    """An Actor has begun performing a Task."""

    event_type: ClassVar[str] = "task_started"
    actor_name: str = ""
    task_name: str = ""
    parent_id: str | None = None