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¶
- Subclass
Sceneand setroute. - Override
expect_readyto wait for the screen, which is what makes a silent run safe. - Add one method per action a viewer would take, built from the helpers below.
- Open it with
open(), which callsgotoand thenexpect_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¶
- Subclass
World, and keep one registry per kind of object. - Add a method that seeds an object under a key, and call
_claimbefore it, which refuses a key the registry already holds. - 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
rootlocator toDropdownorConfirm, and each lookup stays inside it. Confirm: Theacceptmethod has no barrier, so wrap it in one.SearchAndSelect: The driver draws no pointer and records nothing. Callopenbeforechoose.
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
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.
_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
_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
_hover
¶
A method that hovers over an element and holds.
Parameters:
-
locator(Locator) –The locator for the element to hover over.
_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
_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
_tab
¶
A method that opens the tab a name identifies.
Parameters:
-
name(str) –The text shown on the 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
_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
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.
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
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
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
_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.