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_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.- target – the tuple or
-
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 itsusing()
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
-