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:: BrowseTheWeb

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:: BrowseTheWeb

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:: BrowseTheWeb

Examples:

the_actor.attempts_to(Clear.the_text_from_the(NAME_INPUT))

classmethod the_text_from_the(target: Target) → SelfClear

Specify the Target from which to clear the text.

Aliases:

the_text_from()
the_text_from_the_first_of_the()

classmethod the_text_from(target: Target) → SelfClear: Alias for the_text_from_the()

classmethod the_text_from_the_first_of_the(target: Target) → SelfClear: Alias for the_text_from_the()

Click

Aliases: Clicks

class Click(target: Target | None = None)

Click on an element!

Abilities Required:: BrowseTheWeb

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)))

classmethod on_the(target: Target) → SelfClick

Target the element to click on.

Aliases:

on()
on_the_first_of_the()

classmethod on(target: Target) → SelfClick: Alias for on_the().

classmethod on_the_first_of_the(target: Target) → SelfClick: Alias for on_the().

DismissAlert

Aliases: DismissesAlert, DismissTheAlert, DismissesTheAlert

class DismissAlert

Dismiss an alert.

Abilities Required:: BrowseTheWeb

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:: BrowseTheWeb

Examples:

the_actor.attempts_to(DoubleClick.on_the(FILE_ICON))

the_actor.attempts_to(Chain(DoubleClick()))

classmethod on_the(target: Target) → SelfDoubleClick

Target the element to double-click on.

Aliases:

on()
on_the_first_of_the()

classmethod on(target: Target) → SelfDoubleClick: Alias for on_the()

classmethod on_the_first_of_the(target: Target) → SelfDoubleClick: Alias for on_the()

Enter

Aliases: Enters, Press, Presses

class Enter(text: str, mask: bool = False)

Enter text into an input field, or press specific keys.

Abilities Required:: BrowseTheWeb

Examples:

the_actor.attempts_to(
    Enter.the_text("Hello world!").into_the(COMMENT_FIELD)
)

classmethod the_text(text: str) → SelfEnter

Provide the text to enter into the field.

Aliases:

the_keys()

classmethod the_keys(text: str) → SelfEnter: Alias for the_text().

classmethod the_secret(text: str) → SelfEnter

Provide the text to enter into the field, but mark that the text should be masked in the log. The text will appear as “[CENSORED]”.

Aliases:

the_password()

classmethod the_password(text: str) → SelfEnter: Alias for the_secret().

into_the(target: Target) → SelfEnter

Target the element to enter text into.

Aliases:

into()
on()
into_the_first_of_the()

into(target: Target) → SelfEnter: Alias for into_the().

on(target: Target) → SelfEnter: Alias for into_the().

into_the_first_of_the(target: Target): Alias for into_the().

then_hit(*keys: str) → SelfEnter

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()

then_press(*keys: str) → SelfEnter: Alias for then_hit().

Enter2FAToken

Aliases: Enters2FAToken

class Enter2FAToken(target: Target)

Enter the current two-factor authentication token into an input field.

Abilities Required:: BrowseTheWeb AuthenticateWith2FA

Examples:

the_actor.attempts_to(Enter2FAToken.into_the(2FA_INPUT_FIELD))

classmethod into_the(target: Target) → SelfEnter2FAToken

Target the element into which to enter the 2FA token.

Aliases:

into()

classmethod into(target: Target) → SelfEnter2FAToken: Alias for into_the().

GoBack

Aliases: GoesBack

class GoBack

Press the browser back button.

Abilities Required:: BrowseTheWeb

Examples:

the_actor.attempts_to(GoBack())

GoForward

Aliases: GoesForward

class GoForward

Press the browser forward button.

Abilities Required:: BrowseTheWeb

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 a Release Action occurs later in the Chain to release the held key or button.

Abilities Required:: BrowseTheWeb

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() → SelfHoldDown: A convenience method that figures out what operating system the Actor is using and directs the Actor which execution key to hold down.

classmethod left_mouse_button() → SelfHoldDown: Hold down the left mouse button.

on_the(target: Target) → SelfHoldDown: Target an element to hold down left click on.

on(target: Target) → SelfHoldDown: Target an element to hold down left click on.

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:: BrowseTheWeb

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 to_the(target: Target) → SelfMoveMouse

Target an element to move the mouse to.

Aliases:

on_the()
over_the()
over_the_first_of_the()
to_the_first_of_the()

classmethod on_the(target: Target) → SelfMoveMouse: Alias for to_the()

classmethod over_the(target: Target) → SelfMoveMouse: Alias for to_the()

classmethod over_the_first_of_the(target: Target) → SelfMoveMouse: Alias for to_the()

classmethod to_the_first_of_the(target: Target) → SelfMoveMouse: Alias for to_the()

classmethod by_offset(x_offset: int, y_offset: int) → SelfMoveMouse: Specify the offset by which to move the mouse.

with_offset(x_offset: int, y_offset: int) → SelfMoveMouse: 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, then Open("/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:: BrowseTheWeb

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) → SelfOpen

Provide a URL to visit.

Aliases:

browser_on()

classmethod browser_on(location: str | object) → SelfOpen: 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:: BrowseTheWeb

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:: BrowseTheWeb

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 corresponding HoldDown Action was called earlier in the Chain.

Abilities Required:: BrowseTheWeb

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() → SelfRelease: A convenience method that figures out what operating system the Actor is using and tells the Actor which execution key to release.

classmethod left_mouse_button() → SelfRelease: Release the left mouse button.

RespondToThePrompt

Aliases: RespondsToThePrompt, RespondToPrompt, RespondsToPrompt

class RespondToThePrompt(text: str)

Enter text into and accept a javascript prompt.

Abilities Required:: BrowseTheWeb

Examples:

the_actor.attempts_to(
    RespondToThePrompt.with_("Roger, Roger. What's your vector, Victor?")
)

classmethod with_(text: str) → SelfRespondToThePrompt: Provide the text to enter into the prompt.

RightClick

Aliases: RightClicks, ContextClick, ContextClicks

class RightClick(target: Target | None = None)

Right-click on an element, or wherever the cursor currently is.

Abilities Required:: BrowseTheWeb

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.

classmethod on_the(target: Target) → SelfRightClick

Target an element to right-click on.

Aliases:

on()
on_the_first_of_the()

classmethod on(target: Target) → SelfRightClick: Alias for on_the().

classmethod on_the_first_of_the(target: Target) → SelfRightClick: Alias for on_the().

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:: BrowseTheWeb

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) → SelfSaveConsoleLog

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.

and_attach_it(**kwargs: Any) → SelfSaveConsoleLog

Indicate the console log file should be attached to any reports.

This method accepts any additional keywords needed by any adapters attached for Narration.

and_attach_it_with(**kwargs: Any) → SelfSaveConsoleLog

Indicate the console log file should be attached to any reports.

This method accepts any additional keywords needed by any adapters attached for Narration.

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:: BrowseTheWeb

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) → SelfSaveScreenshot

Supply the name and/or filepath for the screenshot.

If only a name is supplied, the screenshot will appear in the current working directory.

and_attach_it(**kwargs: Any) → SelfSaveScreenshot

Indicate the screenshot should be attached to any reports.

This method accepts any additional keywords needed by any adapters attached for Narration.

and_attach_it_with(**kwargs: Any) → SelfSaveScreenshot

Indicate the screenshot should be attached to any reports.

This method accepts any additional keywords needed by any adapters attached for Narration.

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:: BrowseTheWeb

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:: BrowseTheWeb

from_the(target: Target) → SelfSelectByText: Target the dropdown or multi-select field to select the option from.

from_(target: Target) → SelfSelectByText: Target the dropdown or multi-select field to select the option from.

from_the_first_of_the(target: Target) → SelfSelectByText: Target the dropdown or multi-select field to select the option from.

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:: BrowseTheWeb

from_the(target: Target) → SelfSelectByIndex: Target the dropdown or multi-select field to select the option from.

from_(target: Target) → SelfSelectByIndex: Target the dropdown or multi-select field to select the option from.

from_the_first_of_the(target: Target) → SelfSelectByIndex: Target the dropdown or multi-select field to select the option from.

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:: BrowseTheWeb

from_the(target: Target) → SelfSelectByValue: Target the dropdown or multi-select field to select the option from.

from_(target: Target) → SelfSelectByValue: Target the dropdown or multi-select field to select the option from.

from_the_first_of_the(target: Target) → SelfSelectByValue: Target the dropdown or multi-select field to select the option from.

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:: BrowseTheWeb

Examples:

the_actor.attempts_to(SwitchTo(THE_ORDERS_FRAME))

the_actor.attempts_to(SwitchTo.the(ORDERS_FRAME))

the_actor.attempts_to(SwitchTo.default())

classmethod the(target: Target) → SelfSwitchTo: Target an element, probably an iframe, to switch to.

classmethod default() → SelfSwitchTo: 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:: BrowseTheWeb

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:: BrowseTheWeb

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")
)

classmethod for_the(target: Target) → SelfWait

Set the Target to wait for.

Aliases:

for_()

classmethod for_(target: Target) → SelfWait: Alias for for_the()

seconds_for_the(target: Target) → SelfWait: Set the Target to wait for, after changing the default timeout.

second_for(target: Target) → SelfWait: Set the Target to wait for, after changing the default timeout.

second_for_the(target: Target) → SelfWait: Set the Target to wait for, after changing the default timeout.

seconds_for(target: Target) → SelfWait: Set the Target to wait for, after changing the default timeout.

using(strategy: Callable[[...], Any], log_detail: str | None = None) → SelfWait

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) → SelfWait

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) → SelfWait

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) → SelfWait: Set the arguments to pass in to the wait condition.

to_appear() → SelfWait: Use Selenium’s “visibility of element located” strategy.

to_be_clickable() → SelfWait: Use Selenium’s “to be clickable” strategy.

to_disappear() → SelfWait: Use Selenium’s “invisibility of element located” strategy.

to_contain_text(text: str) → SelfWait: Use Selenium’s “text to be present in element” strategy.

property log_message: str: Format the nice log message, or give back the default.