From a769dbc7f1faa79307e2cc9a30b32ad7acaf93bf Mon Sep 17 00:00:00 2001 From: Marcel Wilson Date: Fri, 18 Aug 2023 14:44:41 -0500 Subject: [PATCH] cookbook cleanup based on PR comments --- docs/cookbook.rst | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/cookbook.rst b/docs/cookbook.rst index 6047465..2f52afa 100644 --- a/docs/cookbook.rst +++ b/docs/cookbook.rst @@ -254,14 +254,15 @@ Unless of course something bad happens inside of ``PerformA`` in which case the Using Either =========== -Sometimes we need to try one thing then followed by a different thing when the first one fails. -You could just add a try/except in your code but that breaks up the screenplay pattern. -So there is an action for that; :func:`~screenpy.actions.Either`:: +Sometimes you may need to use a try/except control flow in your test, for +one reason or another. Luckily, your Actor can perform this flow +with the :class:`~screenpy.actions.Either` Action!:: the_actor.will(Either(DoAction()).or_(DoDifferentAction()) -Screenpy will attempt to perform the first action but if an `AssertionError` is raised -screenpy will move on to attempt performing the second action instead. Note that we only catch +Screenpy will attempt to perform the first action (or set of actions) but +if an `AssertionError` is raised screenpy will move on to attempt performing the +second action (or set of actions) instead. Note that we only catch `AssertionError` here allowing for other exceptions to still be raised. The action also allows users to pass in multiple actions similar to how actors can perform @@ -279,3 +280,24 @@ multiple actions in one call:: ) ) + +.. note:: + :class:`~screenpy.actions.Either` will not describe any cleanup for the Actor + after it experiences a failure in the first routine; the Actor will proceed directly + to the second routine. Keep this in mind while defining the two branches of Actions. + +To help illustrate this further here is a real-world example using screenpy_selenium:: + + the_actor.will( + Either( + See(BrowserURL(), HasUrlNetloc(URL)), + CheckIfAuthenticated(), + ).or_( + ClearCache() + Open.their_browser_on(URL()) + Eventually(Enter(username).into(USERNAME_FIELD)), + Enter.the_secret(password).into(PASSWORD_FIELD), + Click.on(SIGN_IN_BUTTON) + ) + ) +