Abilities¶

Abilities allow your Actor to do things. Actors will leverage their abilities to perform actions that require those abilities.

Using Abilities¶

To give an actor an ability, pass it in using the actor’s who_can() or can() methods:

from screenpy import Actor, AnActor
from screenpy.abilities import BrowseTheWeb


# Add abilities on instantiation
Perry = AnActor.named("Perry").who_can(BrowseTheWeb.using_firefox())

# Or add abilities later
Perry = AnActor.named("Perry")
Perry.can(BrowseTheWeb.using_safari())

Granting an ability to an actor allows them to perform any Actions or ask any Questions that require that ability. If an action or a question require an ability that the actor does not have, the actor will raise an UnableToPerformError.

Writing New Abilities¶

There may be other abilities your actors need to possess in order to test your application. You are encouraged to write your own! The only prescribed method for an ability is the forget method, which will complete any cleanup required. For an example, see the forget() method of the BrowseTheWeb ability. A base class for Abilities is provided for convenience: screenpy.abilities.base_ability.BaseAbility

Included Abilities¶

BrowseTheWeb¶

class screenpy.abilities.browse_the_web.BrowseTheWeb(browser: selenium.webdriver.remote.webdriver.WebDriver)¶

The ability to browse the web with a web browser. This ability is meant to be instantiated with its using() static method, which takes in the WebDriver to use, or one of its other “using” methods. A typical invocation looks like:

BrowseTheWeb.using(selenium.webdriver.Firefox())

BrowseTheWeb.using_firefox()

This will create the ability that can be passed in to an actor’s who_can() method.

find(locator: Union[Target, Tuple[selenium.webdriver.common.by.By, str]]) → selenium.webdriver.remote.webelement.WebElement¶: Syntactic sugar for to_find().

find_all(target: Union[Target, Tuple[selenium.webdriver.common.by.By, str]]) → selenium.webdriver.remote.webelement.WebElement¶: Syntactic sugar for to_find_all().

forget() → None¶

Asks the actor to forget how to BrowseTheWeb. This quits the connected browser.

An actor who is exiting will forget all their abilities.

to_find(target: Union[Target, Tuple[selenium.webdriver.common.by.By, str]]) → selenium.webdriver.remote.webelement.WebElement¶

Locates a single element on the page using the given locator.

Parameters:	target – the `Target` or tuple describing the element.
Returns:	WebElement
Raises:	`\|BrowsingError\|`

to_find_all(target: Union[Target, Tuple[selenium.webdriver.common.by.By, str]]) → List[selenium.webdriver.remote.webelement.WebElement]¶

Locates many elements on the page using the given locator.

Parameters:	target – the `Target` or tuple describing the elements.
Returns:	List[WebElement]

to_get(url: str) → screenpy.abilities.browse_the_web.BrowseTheWeb¶

Uses the connected browser to visit the specified 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 function will be appended to the end of it. For example, if you have BASE_URL=http://localhost, then to_get(“/home”) will send your browser to “http://localhost/home”.

If BASE_URL isn’t set, then the passed-in url is assumed to be a fully qualified URL.

Parameters:	url – the URL to visit.
Returns:	`BrowseTheWeb`

to_switch_to(target: Target) → None¶

Switches the browser context to the target.

Parameters:	target – the `Target` or tuple describing the element to switch to.

to_switch_to_alert() → selenium.webdriver.common.alert.Alert¶

Switches to an alert and returns it.

Returns:	Alert
Raises:	`\|BrowsingError\|` – no alert was present to switch to.

to_switch_to_default() → None¶: Switches the browser context back to the default frame.

to_visit(url: str) → screenpy.abilities.browse_the_web.BrowseTheWeb¶: Syntactic sugar for to_get().

to_wait_for(target: Union[Target, Tuple[selenium.webdriver.common.by.By, str]], timeout: int = 20, cond: Callable = <class 'selenium.webdriver.support.expected_conditions.visibility_of_element_located'>)¶

Waits for the element to fulfill the given condition.

Parameters:	target – the tuple or `Target` describing the element. timeout – how many seconds to wait before raising a TimeoutException. Default is 20. cond – the condition to wait for. Default is visibility_of_element_located.
Raises:	`\|BrowsingError\|` – the target did not satisfy the condition in time.

static using(browser: selenium.webdriver.remote.webdriver.WebDriver) → screenpy.abilities.browse_the_web.BrowseTheWeb¶

Specifies the driver to use to browse the web. This can be any WebDriver instance, even a remote one.

Parameters:	browser – the webdriver instance to use.
Returns:	`BrowseTheWeb`

static using_android() → screenpy.abilities.browse_the_web.BrowseTheWeb¶

Creates an uses a default Remote driver instance to connect to a running Appium server and open Chrome on Android. Use this if you don’t need to set anything up for your test browser.

Note that Appium requires non-trivial setup to be able to connect to Android emulators. See the Appium documentation to get started: http://appium.io/docs/en/writing-running-appium/running-tests/

Environment Variables:

APPIUM_HUB_URL: the URL to look for the Appium server. Default: is “http://localhost:4723/wd/hub”
ANDROID_DEVICE_VERSION: the version of the device to put in: the desired capabilities. Default is “10.0”
ANDROID_DEVICE_NAME: the device name to request in the desired: capabilities. Default is “Android Emulator”

Returns:	`BrowseTheWeb`

static using_chrome() → screenpy.abilities.browse_the_web.BrowseTheWeb¶

Creates and uses a default Chrome Selenium webdriver instance. Use this if you don’t need to set anything up for your test browser.

Returns:	`BrowseTheWeb`

static using_firefox() → screenpy.abilities.browse_the_web.BrowseTheWeb¶

Creates and uses a default Firefox Selenium webdriver instance. Use this if you don’t need to set anything up for your test browser.

Returns:	`BrowseTheWeb`

static using_ios() → screenpy.abilities.browse_the_web.BrowseTheWeb¶

Creates an uses a default Remote driver instance to connect to a running Appium server and open Safari on iOS. Use this if you don’t need to set anything up for your test browser.

Note that Appium requires non-trivial setup to be able to connect to iPhone simulators. See the Appium documentation to get started: http://appium.io/docs/en/writing-running-appium/running-tests/

Environment Variables:

APPIUM_HUB_URL: the URL to look for the Appium server. Default: is “http://localhost:4723/wd/hub”
IOS_DEVICE_VERSION: the version of the device to put in the: desired capabilities. Default is “13.1”
IOS_DEVICE_NAME: the device name to request in the desired: capabilities. Default is “iPhone Simulator”

Returns:	`BrowseTheWeb`

static using_safari() → screenpy.abilities.browse_the_web.BrowseTheWeb¶

Creates and uses a default Safari Selenium webdriver instance. Use this if you don’t need to set anything up for your test browser.

Returns:	`BrowseTheWeb`

wait_for(locator: Union[Target, Tuple[selenium.webdriver.common.by.By, str]], timeout: int = 20, cond: Callable = <class 'selenium.webdriver.support.expected_conditions.visibility_of_element_located'>)¶: Syntactic sugar for to_wait_for().

AuthenticateWith2FA¶

class screenpy.abilities.authenticate_with_2fa.AuthenticateWith2FA(otp: pyotp.totp.TOTP)¶

The ability to retrieve a one-time password from a two-factor authenticator. This ability is meant to be instantiated with its using_secret() method, which will take in the 2FA secret, or its using() static method, which takes in an instantiated PyOTP instance. A typical invocation looks like:

AuthenticateWith2FA.using_secret(“KEEPITSECRETKEEPITSAFE”)

AuthenticateWith2FA.using(pyotp_instance)

This will create the ability that can be passed in to an actor’s who_can() method.

forget() → None¶: Cleans up the pyotp instance stored in this ability.

to_get_token() → str¶

Gets the current two-factor token to use as a one-time password.

Returns:	str

static using(otp: pyotp.totp.TOTP) → screenpy.abilities.authenticate_with_2fa.AuthenticateWith2FA¶

Uses an already-created TOTP instance to provide tokens.

Parameters:	otp (pyotp.TOTP) – an instance of a TOTP object.
Returns:	`AuthenticateWith2FA`

static using_secret(secret: str) → screenpy.abilities.authenticate_with_2fa.AuthenticateWith2FA¶

Creates a TOTP instance with the given secret.

Parameters:	secret – the secret given by the 2FA service. You may need to decode a QR code to get this secret.
Returns:	`AuthenticateWith2FA`