Skip to content

Scenes And Components

Overview

A Scene is one screen of the application, so a test reads as a list of steps rather than a list of selectors. A component drives a widget that appears on many screens, and a World names the objects a demo has seeded.

Write A Scene

  1. Subclass Scene and set route.
  2. Override expect_ready to wait for the screen, which is what makes a silent run safe.
  3. Add one method per action a viewer would take, built from the helpers below.
  4. Open it with open(), which calls goto and then expect_ready.

The examples/order_search.py program is a complete scene.

Helper Description
_click, _fill, _select, _check, _press, _hover Each helper performs the action through the demo and then holds.
_tab The helper clicks a tab by its name.
_teach_focus The helper shows the viewer an element.
_teach_click The helper shows the viewer an element and then clicks it.

A _teach_focus with a headline waits for the element in both modes, and one with a label alone does not. A narrated scene action holds for twice the step, so lower DEMO_STEP_MS for a demo built from scenes.

Name The Seeded Objects

  1. Subclass World, and keep one registry per kind of object.
  2. Add a method that seeds an object under a key, and call _claim before it, which refuses a key the registry already holds.
  3. Add a method that reads the object back with _require, which names the key it could not find.
Helper Description
_claim The helper raises ValueError for a key that was seeded already.
_require The helper returns the object under a key, and raises KeyError for a key that was never seeded.

Use A Component

Component Description
Modal The driver opens a dialog from its control, fills it by label, and submits it.
Dropdown The driver opens a menu from a trigger and picks one of its actions.
Confirm The driver accepts the inline prompt between an action and its effect.
Navigator The driver moves through a navigation menu by the text on its links.
SearchAndSelect The driver picks one choice from a dropdown field.

Subclass a component and override the selectors that differ, such as trigger_selector. The examples/row_menu.py program does this for one row of a table.

  • One row of many: Pass a root locator to Dropdown or Confirm, and each lookup stays inside it.
  • Confirm: The accept method has no barrier, so wrap it in one.
  • SearchAndSelect: The driver draws no pointer and records nothing. Call open before choose.

Reference

The protected helpers are the contract between these classes and a subclass, so this page documents them in full.

limelight.Scene

A page object for a single screen of a demo.

This class pairs a route with the assertions that prove the screen has loaded. A subclass sets the route and overrides expect_ready().

The protected helpers are the vocabulary an actor is written in. Each one performs an action through the demo and then holds, so a narrated run shows the drawn pointer land before the next step begins and a silent run pays nothing for the hold. A scene calls them rather than a Playwright locator method, because a bare click moves the real mouse without moving the drawn one.

class OrderScene(Scene):
    route = 'sales:order:page:list'

    def expect_ready(self) -> None:
        expect(self.search_field).to_be_visible()

    def search(self, text: str) -> None:
        self._teach_focus(self.search_field, headline='Search', label='Search')

        self._fill(self.search_field, text)

The constructor for the Scene class.

Parameters:

  • demo (Demo) –

    The demo that drives the browser for this scene.

Source code in limelight/scene.py
def __init__(self, demo: Demo) -> None:
    """
    The constructor for the Scene class.

    :param demo: The demo that drives the browser for this scene.
    """

    self.demo = demo

route = '' class-attribute instance-attribute

demo = demo instance-attribute

_check

A method that ticks a checkbox and holds.

Parameters:

  • locator (Locator) –

    The locator for the checkbox.

Source code in limelight/scene.py
def _check(self, locator: Locator) -> None:
    """
    A method that ticks a checkbox and holds.

    :param locator: The locator for the checkbox.
    """

    self.demo.check(locator)
    self.demo.pause()

_click

A method that clicks an element and holds.

Parameters:

  • locator (Locator) –

    The locator for the element to click.

  • force (bool, default: False ) –

    Whether to click without waiting for the element to be actionable.

Source code in limelight/scene.py
def _click(self, locator: Locator, *, force: bool = False) -> None:
    """
    A method that clicks an element and holds.

    :param locator: The locator for the element to click.
    :param force: Whether to click without waiting for the element to be actionable.
    """

    self.demo.click(locator, force=force)
    self.demo.pause()

_fill

A method that puts text into a field and holds.

Parameters:

  • locator (Locator) –

    The locator for the field.

  • value (str) –

    The text to put into the field.

Source code in limelight/scene.py
def _fill(self, locator: Locator, value: str) -> None:
    """
    A method that puts text into a field and holds.

    :param locator: The locator for the field.
    :param value: The text to put into the field.
    """

    self.demo.fill(locator, value)
    self.demo.pause()

_hover

A method that hovers over an element and holds.

Parameters:

  • locator (Locator) –

    The locator for the element to hover over.

Source code in limelight/scene.py
def _hover(self, locator: Locator) -> None:
    """
    A method that hovers over an element and holds.

    :param locator: The locator for the element to hover over.
    """

    self.demo.hover(locator)
    self.demo.pause()

_press

A method that presses a key on an element and holds.

Parameters:

  • locator (Locator) –

    The locator for the element the key is pressed on.

  • key (str) –

    The key to press.

Source code in limelight/scene.py
def _press(self, locator: Locator, key: str) -> None:
    """
    A method that presses a key on an element and holds.

    :param locator: The locator for the element the key is pressed on.
    :param key: The key to press.
    """

    self.demo.press(locator, key)
    self.demo.pause()

_select

A method that picks an option by its label and holds.

Parameters:

  • locator (Locator) –

    The locator for the select element.

  • option_label (str) –

    The visible text of the option to pick.

Source code in limelight/scene.py
def _select(self, locator: Locator, option_label: str) -> None:
    """
    A method that picks an option by its label and holds.

    :param locator: The locator for the select element.
    :param option_label: The visible text of the option to pick.
    """

    self.demo.select(locator, option_label)
    self.demo.pause()

_tab

A method that opens the tab a name identifies.

Parameters:

  • name (str) –

    The text shown on the tab.

Source code in limelight/scene.py
def _tab(self, name: str) -> None:
    """
    A method that opens the tab a name identifies.

    :param name: The text shown on the tab.
    """

    tab = self.demo.page.get_by_role('tab', name=name)

    self._click(tab)

_teach_click

A method that shows the viewer an element and then clicks it.

Parameters:

  • locator (Locator) –

    The locator for the element to show and click.

  • headline (str, default: '' ) –

    The narration headline, or an empty string for none.

  • label (str, default: '' ) –

    The caption shown beside the element.

  • body (str, default: '' ) –

    The narration body shown under the headline.

  • step (str, default: '' ) –

    The step label the narration carries.

Raises:

  • AssertionError –

    If the element is narrated and never appears.

Source code in limelight/scene.py
def _teach_click(
    self,
    locator: Locator,
    *,
    headline: str = '',
    label: str = '',
    body: str = '',
    step: str = '',
) -> None:
    """
    A method that shows the viewer an element and then clicks it.

    :param locator: The locator for the element to show and click.
    :param headline: The narration headline, or an empty string for none.
    :param label: The caption shown beside the element.
    :param body: The narration body shown under the headline.
    :param step: The step label the narration carries.
    :raises AssertionError: If the element is narrated and never appears.
    """

    self._teach_focus(locator, headline=headline, label=label, body=body, step=step)

    self._click(locator)

_teach_focus

A method that shows the viewer an element, once it is on the page.

A headline narrates the element in full, and the element is waited for before anything is said about it, so the step is a barrier in a silent run as well as a caption in a narrated one. A label alone spotlights the element without narration, and a call with neither shows nothing.

Parameters:

  • locator (Locator) –

    The locator for the element to show.

  • headline (str, default: '' ) –

    The narration headline, or an empty string for none.

  • label (str, default: '' ) –

    The caption shown beside the element.

  • body (str, default: '' ) –

    The narration body shown under the headline.

  • step (str, default: '' ) –

    The step label the narration carries.

Raises:

  • AssertionError –

    If the element is narrated and never appears.

Source code in limelight/scene.py
def _teach_focus(
    self,
    locator: Locator,
    *,
    headline: str = '',
    label: str = '',
    body: str = '',
    step: str = '',
) -> None:
    """
    A method that shows the viewer an element, once it is on the page.

    A headline narrates the element in full, and the element is waited for
    before anything is said about it, so the step is a barrier in a silent
    run as well as a caption in a narrated one. A label alone spotlights the
    element without narration, and a call with neither shows nothing.

    :param locator: The locator for the element to show.
    :param headline: The narration headline, or an empty string for none.
    :param label: The caption shown beside the element.
    :param body: The narration body shown under the headline.
    :param step: The step label the narration carries.
    :raises AssertionError: If the element is narrated and never appears.
    """

    if headline:
        self.demo.reveal(locator, headline=headline, body=body, step=step, label=label)

        return

    if label:
        self.demo.spotlight(locator, label=label)

expect_ready

A method that waits until the scene has finished loading.

The base implementation does nothing, so a scene that needs to settle before the next step overrides this with its own assertions.

Source code in limelight/scene.py
def expect_ready(self) -> None:
    """
    A method that waits until the scene has finished loading.

    The base implementation does nothing, so a scene that needs to settle
    before the next step overrides this with its own assertions.
    """

open

A method that navigates to the scene route and waits for it to be ready.

Parameters:

  • query (Mapping[str, object] | None, default: None ) –

    The query string parameters appended to the URL, or None for none.

  • url_kwargs (object, default: {} ) –

    The arguments used to reverse the route into a URL.

Returns:

  • Self –

    The scene itself, so calls can be chained.

Raises:

  • ValueError –

    If the route has not been set on the subclass.

Source code in limelight/scene.py
def open(
    self,
    *,
    query: Mapping[str, object] | None = None,
    **url_kwargs: object,
) -> Self:
    """
    A method that navigates to the scene route and waits for it to be ready.

    :param query: The query string parameters appended to the URL, or None for none.
    :param url_kwargs: The arguments used to reverse the route into a URL.
    :return: The scene itself, so calls can be chained.
    :raises ValueError: If the route has not been set on the subclass.
    """

    if not self.route:
        message = f'{type(self).__name__}.route must be set before open()'
        raise ValueError(message)

    self.demo.goto(self.route, query=query, **url_kwargs)
    self.expect_ready()

    return self

limelight.World

A registry of the objects a demo has seeded, addressed by name.

A demo reads better when it names what it is looking at rather than carrying a model instance from step to step, so a subclass adds one method per kind that seeds an object under a key, and one that reads it back. This class supplies the two halves those methods share: a claim that refuses to seed the same key twice, and a lookup that names the key it could not find.

class DemoWorld(World):
    def __init__(self, user):
        super().__init__(user)

        self._orders = {}

    def add_order(self, key, **field_data):
        self._claim(self._orders, key, kind='order')

        self._orders[key] = create_test_order(name=key, **field_data)

        return self

    def order(self, key):
        return self._require(self._orders, key, kind='order')

The constructor for the World class.

Parameters:

  • user (object) –

    The user the demo is signed in as.

Source code in limelight/world.py
def __init__(self, user: object) -> None:
    """
    The constructor for the World class.

    :param user: The user the demo is signed in as.
    """

    self.user = user

user = user instance-attribute

_claim staticmethod

A method that refuses a key the registry already holds.

Parameters:

  • registry (Mapping[str, object]) –

    The registry the key is claimed in.

  • name (str) –

    The key being claimed.

  • kind (str) –

    The kind of object the registry holds, named in the failure.

Raises:

  • ValueError –

    If the key is already taken.

Source code in limelight/world.py
@staticmethod
def _claim(registry: Mapping[str, object], name: str, *, kind: str) -> None:
    """
    A method that refuses a key the registry already holds.

    :param registry: The registry the key is claimed in.
    :param name: The key being claimed.
    :param kind: The kind of object the registry holds, named in the failure.
    :raises ValueError: If the key is already taken.
    """

    if name in registry:
        message = f'{kind} already seeded: {name}'
        raise ValueError(message)

_require staticmethod

A method that reads a key the registry must hold.

Parameters:

  • registry (Mapping[str, T]) –

    The registry the key is read from.

  • name (str) –

    The key being read.

  • kind (str) –

    The kind of object the registry holds, named in the failure.

Returns:

  • T –

    The object seeded under the key.

Raises:

  • KeyError –

    If the key was never seeded.

Source code in limelight/world.py
@staticmethod
def _require(registry: Mapping[str, T], name: str, *, kind: str) -> T:
    """
    A method that reads a key the registry must hold.

    :param registry: The registry the key is read from.
    :param name: The key being read.
    :param kind: The kind of object the registry holds, named in the failure.
    :return: The object seeded under the key.
    :raises KeyError: If the key was never seeded.
    """

    if name not in registry:
        message = f'{kind} not seeded: {name}'
        raise KeyError(message)

    return registry[name]