Additional Actions
ScreenPy Selenium adds many additional Actions. For the base Action list, see ScreenPy’s Actions API reference.
AcceptAlert
Aliases: AcceptsAlert
- class AcceptAlert
Accept an alert!
- Abilities Required:
Examples:
the_actor.attempts_to(AcceptAlert())
Chain
Aliases: Chains
- class Chain(*actions: Chainable)
Group a series of chainable Actions together.
A Chain Action is expected to be instantiated with a list of Actions to perform in a series.
Note: Several Actions cannot be Chained, and will raise an exception.
- Abilities Required:
Examples:
the_actor.attempts_to( Chain(Hover.on_the(MENU_ICON), Click.on_the(SUBMENU_LINK)) )
Clear
Aliases: Clears
- class Clear(target: Target)
Clear the text from an input field.
- Abilities Required:
Examples:
the_actor.attempts_to(Clear.the_text_from_the(NAME_INPUT))
- classmethod the_text_from_the(target: Target) Self
Specify the Target from which to clear the text.
- classmethod the_text_from(target: Target) Self
Alias for
the_text_from_the()
.
- classmethod the_text_from_the_first_of_the(target: Target) Self
Alias for
the_text_from_the()
.
Click
Aliases: Clicks
- class Click(target: Target | None = None)
Click on an element!
- Abilities Required:
Examples:
the_actor.attempts_to(Click.on_the(PROFILE_LINK)) the_actor.attempts_to(Click.on(THE_LOGIN_LINK)) the_actor.attempts_to(Chain(Click(THE_LOGIN_LINK)))
DismissAlert
Aliases: DismissesAlert
,
DismissTheAlert
,
DismissesTheAlert
- class DismissAlert
Dismiss an alert.
- Abilities Required:
Examples:
the_actor.attempts_to(DismissAlert())
DoubleClick
Aliases: DoubleClicks
- class DoubleClick(target: Target | None = None)
Double-click on an element, or wherever the cursor currently is.
- Abilities Required:
Examples:
the_actor.attempts_to(DoubleClick.on_the(FILE_ICON)) the_actor.attempts_to(Chain(DoubleClick()))
Enter
Aliases: Enters
,
Press
,
Presses
- class Enter(text: str, mask: bool = False)
Enter text into an input field, or press specific keys.
- Abilities Required:
Examples:
the_actor.attempts_to( Enter.the_text("Hello world!").into_the(COMMENT_FIELD) )
- classmethod the_text(text: str) Self
Provide the text to enter into the field.
- Aliases:
- classmethod the_keys(text: str) Self
Alias for
the_text()
.
- classmethod the_secret(text: str) Self
Provide the text to enter into the field, but mask it in logging.
The text will appear as “[CENSORED]”.
- Aliases:
- classmethod the_password(text: str) Self
Alias for
the_secret()
.
- into(target: Target) Self
Alias for
into_the()
.
- on(target: Target) Self
Alias for
into_the()
.
- into_the_first_of_the(target: Target) Self
Alias for
into_the()
.
- then_hit(*keys: str) Self
Supply additional keys to hit after entering the text.
- Args:
- keys: the keys to hit afterwards. These are probably the
constants from Selenium’s
Keys
.
- Aliases:
- then_press(*keys: str) Self
Alias for
then_hit()
.
- property text_to_log: str
Get a proper representation of the text.
Enter2FAToken
Aliases: Enters2FAToken
- class Enter2FAToken(target: Target)
Enter the current two-factor authentication token into an input field.
- Abilities Required:
Examples:
the_actor.attempts_to(Enter2FAToken.into_the(2FA_INPUT_FIELD))
- classmethod into_the(target: Target) Self
Target the element into which to enter the 2FA token.
- Aliases:
- classmethod into(target: Target) Self
Alias for
into_the()
.
GoBack
Aliases: GoesBack
- class GoBack
Press the browser back button.
- Abilities Required:
Examples:
the_actor.attempts_to(GoBack())
GoForward
Aliases: GoesForward
- class GoForward
Press the browser forward button.
- Abilities Required:
Examples:
the_actor.attempts_to(GoForward())
HoldDown
Aliases: HoldsDown
- class HoldDown(key: str | None = None, lmb: bool = False)
Hold down the specified key or left mouse button.
This Action can only be used with
Chain
, and it is expected that aRelease
Action occurs later in the Chain to release the held key or button.- Abilities Required:
Examples:
the_actor.attempts_to(Chain(HoldDown(Keys.SHIFT)) the_actor.attempts_to(Chain(HoldDown.command_or_control_key())) the_actor.attempts_to( Chain(HoldDown.left_mouse_button().on_the(DRAGGABLE_BOX)) )
- classmethod command_or_control_key() Self
A convenience method for supporting multiple operating systems.
Figures out what operating system the Actor is using and directs the Actor which execution key to hold down.
- classmethod left_mouse_button() Self
Hold down the left mouse button.
MoveMouse
Aliases: MovesMouse
,
Hover
,
Hovers
- class MoveMouse(offset: tuple[int, int] | None = None, target: Target | None = None, description: str = '')
Move the mouse to a specific element or by a pixel offset.
The x and y offsets are measured in pixels, with the “origin” at the top left of the screen.
To move left, give a negative x_offset.
To move right, give a positive x_offset.
To move up, give a negative y_offset.
To move down, give a positive y_offset.
- Abilities Required:
Examples:
the_actor.attempts_to(MoveMouse.to_the(HAMBURGER_MENU)) the_actor.attempts_to(MoveMouse.by_offset(500, -200)) the_actor.attempts_to( Chain(MoveMouse.to_the(HAMBURGER_MENU).with_offset(500, -200)) )
- classmethod by_offset(x_offset: int, y_offset: int) Self
Specify the offset by which to move the mouse.
- with_offset(x_offset: int, y_offset: int) Self
Specify the mouse should be moved to the element with an offset.
Open
Aliases: Opens
,
Visit
,
Visits
- class Open(location: str | object)
Go to a specific URL!
This Action supports using the BASE_URL environment variable to set a base URL. If you set BASE_URL, the url passed in to this Action will be appended to the end of it. For example, if you have
BASE_URL=http://localhost
, thenOpen("/home")
will send your browser to “http://localhost/home”.If you pass in an object, make sure the object has a
url
property that can be referenced by this Action.- Abilities Required:
Examples:
the_actor.attempts_to(Open.their_browser_on(HOMEPAGE_URL)) # using environment variable BASE_URL the_actor.attempts_to(Open.their_browser_on("/login")) # using a page object with HomepageObject.url the_actor.attempts_to(Open.browser_on(HomepageObject))
- classmethod their_browser_on(location: str | object) Self
Provide a URL to visit.
- Aliases:
- classmethod browser_on(location: str | object) Self
Alias for
their_browser_on()
.
Pause
Aliases: Pauses
- class Pause(number: float)
An extension of ScreenPy’s Pause which can also be Chained.
The Actor will pause for a contemplative moment, taking no actions until the duration has expired.
- Abilities Required:
Examples:
the_actor.attempts_to( Pause.for_(300).seconds_because("it's time for their break.") ) the_actor.attempts_to( Chain( MoveMouse.to_the(DROPDOWN_MENU), Pause.for_(2).seconds_because( "the fancy menu slide-in animation needs to finish." ), Click.on_the(SUBMENU_OPTION), ) )
RefreshPage
Aliases: RefreshesPage
,
Refresh
,
Refreshes
,
Reload
,
Reloads
,
ReloadPage
,
ReloadsPage
- class RefreshPage
Refresh the browser page!
- Abilities Required:
Examples:
the_actor.attempts_to(RefreshPage())
Release
Aliases: Releases
- class Release(key: str | None = None, lmb: bool = False)
Release the specified key or left mouse button.
This Action can only be used with
Chain
, and it expects that a correspondingHoldDown
Action was called earlier in the Chain.- Abilities Required:
Examples:
the_actor.attempts_to(Release.left_mouse_button()) the_actor.attempts_to(Release(Keys.SHIFT)) the_actor.attempts_to(Release.command_or_control_key())
- classmethod command_or_control_key() Self
A convenience method for supporting multiple operating systems.
Figures out what operating system the Actor is using and tells the Actor which execution key to release.
- classmethod left_mouse_button() Self
Release the left mouse button.
RespondToThePrompt
Aliases: RespondsToThePrompt
,
RespondToPrompt
,
RespondsToPrompt
RightClick
Aliases: RightClicks
,
ContextClick
,
ContextClicks
- class RightClick(target: Target | None = None)
Right-click on an element, or wherever the cursor currently is.
- Abilities Required:
Examples:
the_actor.attempts_to(RightClick.on_the(HERO_IMAGE)) the_actor.attempts_to(Chain(RightClick()))
Note: Most of the time, the context menu that appears after a user right-clicks is not interactable through Selenium, because it is an application-level menu. A website will need to have implemented a custom context menu made of web elements to be able to interact with it.
SaveConsoleLog
Aliases: SavesConsoleLog
- class SaveConsoleLog(path: str)
Save the Actor’s browser’s console log.
Note that you may need to set additional driver properties when creating the Actor’s browser to enable the console log (e.g. setting
capabilities["goog:loggingPrefs"] = {"browser": "ALL"}
.)Use the
and_attach_it()
method to indicate that this text file should be attached to all reports through the Narrator’s adapters. This method also accepts any keyword arguments those adapters might require.- Abilities Required:
Examples:
the_actor.attempts_to(SaveConsoleLog("console_log.txt")) the_actor.attempts_to(SaveConsoleLog.as_(filepath)) # attach file to the Narrator's reports (behavior depends on adapter). the_actor.attempts_to(SaveConsoleLog.as_(filepath).and_attach_it()) # using screenpy_adapter_allure plugin! from allure_commons.types import AttachmentType the_actor.attempts_to( SaveConsoleLog.as_(filepath).and_attach_it_with( attachment_type=AttachmentTypes.TEXT, ), )
- classmethod as_(path: str) Self
Supply the name and/or filepath for the saved text file.
If only a name is supplied, the text file will appear in the current working directory.
SaveScreenshot
Aliases: SavesScreenshot
,
TakeScreenshot
,
TakesScreenshot
- class SaveScreenshot(path: str)
Save a screenshot from the actor’s browser.
Use the
and_attach_it()
method to indicate that this screenshot should be attached to all reports through the Narrator’s adapters. This method also accepts any keyword arguments those adapters might require.- Abilities Required:
Examples:
the_actor.attempts_to(SaveScreenshot("screenshot.png")) the_actor.attempts_to(SaveScreenshot.as_(filepath)) # attach file to the Narrator's reports (behavior depends on adapter). the_actor.attempts_to(SaveScreenshot.as_(filepath).and_attach_it()) # using screenpy_adapter_allure plugin! from allure_commons.types import AttachmentType the_actor.attempts_to( SaveScreenshot.as_(filepath).and_attach_it_with( attachment_type=AttachmentTypes.PNG, ), )
- classmethod as_(path: str) Self
Supply the name and/or filepath for the screenshot.
If only a name is supplied, the screenshot will appear in the current working directory.
Select
Aliases: Selects
- class Select
Select an option from a dropdown menu.
This is an entry point that will create the correct specific Select Action to be used, depending on how the option needs to be selected.
- Abilities Required:
Examples:
the_actor.attempts_to( Select.the_option_named("January").from_the(MONTH_DROPDOWN) ) the_actor.attempts_to( Select.the_option_at_index(0).from_the(MONTH_DROPDOWN) ) the_actor.attempts_to( Select.the_option_with_value("jan").from_the(MONTH_DROPDOWN) )
- static the_option_named(text: str) SelectByText
Select the option by its text.
- static the_option_at_index(index: int | str) SelectByIndex
Select the option by its index. This index is 0-based.
- static the_option_with_value(value: int | str) SelectByValue
Select the option by its value.
Aliases: SelectsByText
- class SelectByText(text: str, target: Target | None = None)
Select an option in a dropdown or multi-select field by its text.
This Action will probably not be used directly, rather it will be returned by calling
the_option_named()
.- Abilities Required:
Aliases: SelectsByIndex
- class SelectByIndex(index: int | str, target: Target | None = None)
Select an option in a dropdown or multi-select field by its index.
This Action will probably not be used directly, rather it will be returned by calling
the_option_at_index()
.- Abilities Required:
Aliases: SelectsByValue
- class SelectByValue(value: int | str, target: Target | None = None)
Select an option in a dropdown or multi-select field by its value.
This Action will probably not be used directly, rather it will be returned by calling
the_option_with_value()
.- Abilities Required:
SwitchTo
Aliases: SwitchesTo
- class SwitchTo(target: Target | None, frame_to_log: str)
Switch to an element, most likely an iframe, or back to default.
- Abilities Required:
Examples:
the_actor.attempts_to(SwitchTo(THE_ORDERS_FRAME)) the_actor.attempts_to(SwitchTo.the(ORDERS_FRAME)) the_actor.attempts_to(SwitchTo.default())
- classmethod default() Self
Switch back to the default frame, the browser window.
SwitchToTab
Aliases: SwitchesToTab
,
SwitchToWindow
,
SwitchesToWindow
- class SwitchToTab(number: int)
Switch to a specified tab or window.
- Abilities Required:
Examples:
the_actor.attempts_to(SwitchToTab(4))
Wait
Aliases: Waits
- class Wait(seconds: float | None = None, args: Iterable[Any] | None = None)
Wait for the application to fulfill a given condition.
- Abilities Required:
Examples:
the_actor.attempts_to(Wait.for_the(LOGIN_FORM)) the_actor.attempts_to( Wait.for_the(WELCOME_BANNER).to_contain_text("Welcome!") ) the_actor.attempts_to(Wait.for(CONFETTI).to_disappear()) the_actor.attempts_to( Wait(10).seconds_for_the(PARADE_FLOATS).to(float_on_by) ) the_actor.attempts_to( Wait().using(cookies_to_contain).with_("delicious=true") ) the_actor.attempts_to( Wait().using( cookies_to_contain, "for a cookie that has {0}" ).with_("delicious=true") )
- seconds_for_the(target: Target) Self
Set the Target to wait for, after changing the default timeout.
- second_for_the(target: Target) Self
Set the Target to wait for, after changing the default timeout.
- using(strategy: Callable[..., Any], log_detail: str | None = None) Self
Use the given strategy to wait for the Target.
- Args:
- strategy: the condition to use to wait. This can be one of
Selenium’s Expected Conditions, or any custom Callable that returns a boolean.
- log_detail: a nicer-looking message to log than the default.
You can use {0}, {1}, etc. to reference specific arguments passed into .with_() or .for_the().
- to(strategy: Callable[..., Any], log_detail: str | None = None) Self
Use the given strategy to wait for the Target.
- Args:
- strategy: the condition to use to wait. This can be one of
Selenium’s Expected Conditions, or any custom Callable that returns a boolean.
- log_detail: a nicer-looking message to log than the default.
You can use {0}, {1}, etc. to reference specific arguments passed into .with_() or .for_the().
- seconds_using(strategy: Callable[..., Any], log_detail: str | None = None) Self
Use the given strategy to wait for the Target.
- Args:
- strategy: the condition to use to wait. This can be one of
Selenium’s Expected Conditions, or any custom Callable that returns a boolean.
- log_detail: a nicer-looking message to log than the default.
You can use {0}, {1}, etc. to reference specific arguments passed into .with_() or .for_the().
- with_(*args: Any) Self
Set the arguments to pass in to the wait condition.
- to_appear() Self
Use Selenium’s “visibility of element located” strategy.
- to_be_clickable() Self
Use Selenium’s “to be clickable” strategy.
- to_disappear() Self
Use Selenium’s “invisibility of element located” strategy.
- to_contain_text(text: str) Self
Use Selenium’s “text to be present in element” strategy.
- property log_message: str
Format the nice log message, or give back the default.