Merge pull request #82 from testla-project/80-documentation-of-orskiponfail-and-failasfalse

80 documentation of orskiponfail and failasfalse

Author: munichbughunter

__tests__/failure-handling.spec.ts

@@ -0,0 +1,38 @@
+import { expect, test as base } from '@playwright/test';
+import { Actor } from '@testla/screenplay';
+import { BrowseTheWeb, Navigate, Click, Element } from '../src/web';
+
+type MyActors = {
+    actor: Actor;
+};
+
+const test = base.extend<MyActors>({
+    actor: async ({ browser }, use) => {
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        const actor = Actor.named('TestActor')
+            .can(BrowseTheWeb.using(page));
+        await use(actor);
+    },
+});
+
+test.describe('Testing screenplay-playwright-js failure handling', () => {
+    test('orSkipOnFail', async ({ actor }) => {
+        await actor.attemptsTo(
+            Navigate.to('https://google.de'),
+            Click.on('#not-existing-element', { timeout: 1000 }).orSkipOnFail,
+        );
+    });
+
+    test('failAsFalse', async ({ actor }) => {
+        await actor.attemptsTo(
+            Navigate.to('https://google.de'),
+        );
+
+        const shallBeFalse = await actor.asks(
+            Element.toBe.visible('#not-existing-element', { timeout: 1000 }).failAsFalse,
+        );
+
+        await expect(shallBeFalse).toBe(false);
+    });
+});

docs/guides/failing_steps/failing_steps.md

@@ -0,0 +1,39 @@
+[Back to overview](../guides.md)
+
+# Handle Failing Steps
+
+In general tests break when a step fails. This happens if an action or task is not successful or when a question cannot be answered positive.
+
+But what if an action or tasks is allowed to fail based on the current state of the system under test or when you want to react conditionally on failing questions? Testla offers you the follwing options for this.
+
+## Proceeding with the test when an action/task fails
+
+You may have actions or tasks which might (expectedly) fail during the test. An example is to click an element if it is present while it is also fine to proceed with the test when the element is not available.
+
+This can be achieved as follows:
+
+```javascript
+await actor.attemptsTo(
+    // this action might fail but the test will continue
+    Click.on('#eventually-available').orSkipOnFail,
+    Click.on('#definitely-available'),
+);
+```
+
+## Use failing questions for test flow controls
+
+In some cases you may want to ask questions to find out about the status of the system under test to make decisions on how to move on with your test. In order to not fail a test but receive information about questions being answered negative you can use `failAsFalse` on a question which then returns a boolean value instead.
+
+```javascript
+// find out if question was answered with false
+const wasLoggedIn = await actors.asks(
+    Login.toBe.successful().failAsFalse,
+);
+
+// proceed based on answer from above
+if (wasLoggedIn === false) {
+    // some code to be executed on false case
+}
+```
+
+[Back to overview](../guides.md)

docs/guides/guides.md

@@ -11,6 +11,8 @@
   - [Write your own Tasks](./advanced_test_setup/create_task.md)
   - [Write your own Questions](./advanced_test_setup/create_question.md)
   - [Use it in your test](./advanced_test_setup/write_tests.md)
+- **Handle Failing Steps**
+  - [Failing Steps](./failing_steps/failing_steps.md) - Handling for failing actions, tasks and questions
 - **Aliasing**
   - [Ability Aliasing](./ability_aliasing/ability_aliasing.md) - Using the same ability with different configurations
 - **Frame Handling**

docs/guides/logging/logging.md

@@ -2,8 +2,6 @@
 
 # Logging
 
-> This feature is currently in experimental stage and might see bigger changes.
-
 Testla comes with logging which helps you to debug your test code. When logging is enabled all activities an actor triggers are logged in a comprehensive way to stdout. To enable logging set the DEBUG environment variable as follows:
 
 ```typescript

docs/screenplay_elements/API/Actions/delete.md

@@ -16,6 +16,7 @@ The `Delete` class provides a convenient way to perform HTTP DELETE requests. It
     - [withHeaders](#withheaders)
     - [withResponseBodyFormat](#withresponsebodyformat)
     - [withAbilityAlias](#withabilityalias)
+    - [orSkipOnFail](#orskiponfail)
 
 ## Class Overview
 
@@ -80,4 +81,15 @@ public withAbilityAlias(alias: string): Delete;
   - `alias` - The alias.
 - **Returns:** `Delete` - Returns the current action.
 
+### orSkipOnFail
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get orSkipOnFail(): Delete;
+```
+
+- **Description:** Allows to skip an action on fail.
+- **Returns:** `Delete` - Returns the current action.
+
 [Back to overview](../../screenplay_elements.md)

docs/screenplay_elements/API/Actions/get.md

@@ -16,6 +16,7 @@ The `Get` class provides a convenient way to perform HTTP GET requests. It allow
     - [withHeaders](#withheaders)
     - [withResponseBodyFormat](#withresponsebodyformat)
     - [withAbilityAlias](#withabilityalias)
+    - [orSkipOnFail](#orskiponfail)
 
 ## Class Overview
 
@@ -80,4 +81,15 @@ public withAbilityAlias(alias: string): Get;
   - `alias` - The alias.
 - **Returns:** `Get` - Returns the current action.
 
+### orSkipOnFail
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get orSkipOnFail(): Get;
+```
+
+- **Description:** Allows to skip an action on fail.
+- **Returns:** `Get` - Returns the current action.
+
 [Back to overview](../../screenplay_elements.md)

docs/screenplay_elements/API/Actions/head.md

@@ -15,6 +15,7 @@ The `Head` class provides a convenient way to perform HTTP HEAD requests. It all
     - [from](#from)
     - [withHeaders](#withheaders)
     - [withAbilityAlias](#withabilityalias)
+    - [orSkipOnFail](#orskiponfail)
 
 ## Class Overview
 
@@ -68,4 +69,15 @@ public withAbilityAlias(alias: string): Head;
   - `alias` - The alias.
 - **Returns:** `Head` - Returns the current action.
 
+### orSkipOnFail
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get orSkipOnFail(): Head;
+```
+
+- **Description:** Allows to skip an action on fail.
+- **Returns:** `Head` - Returns the current action.
+
 [Back to overview](../../screenplay_elements.md)

docs/screenplay_elements/API/Actions/patch.md

@@ -17,6 +17,7 @@ The `Patch` class provides a convenient way to perform HTTP PATCH requests. It a
     - [withHeaders](#withheaders)
     - [withResponseBodyFormat](#withresponsebodyformat)
     - [withAbilityAlias](#withabilityalias)
+    - [orSkipOnFail](#orskiponfail)
 
 ## Class Overview
 
@@ -92,4 +93,15 @@ public withAbilityAlias(alias: string): Patch;
   - `alias` - The alias.
 - **Returns:** `Patch` - Returns the current action.
 
+### orSkipOnFail
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get orSkipOnFail(): Patch;
+```
+
+- **Description:** Allows to skip an action on fail.
+- **Returns:** `Patch` - Returns the current action.
+
 [Back to overview](../../screenplay_elements.md)

docs/screenplay_elements/API/Actions/post.md

@@ -17,6 +17,7 @@ The `Post` class provides a convenient way to perform HTTP POST requests. It all
     - [withHeaders](#withheaders)
     - [withResponseBodyFormat](#withresponsebodyformat)
     - [withAbilityAlias](#withabilityalias)
+    - [orSkipOnFail](#orskiponfail)
 
 ## Class Overview
 
@@ -92,4 +93,15 @@ public withAbilityAlias(alias: string): Post;
   - `alias` - The alias.
 - **Returns:** `Post` - Returns the current action.
 
+### orSkipOnFail
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get orSkipOnFail(): Post;
+```
+
+- **Description:** Allows to skip an action on fail.
+- **Returns:** `Post` - Returns the current action.
+
 [Back to overview](../../screenplay_elements.md)

docs/screenplay_elements/API/Actions/put.md

@@ -17,6 +17,7 @@ The `Put` class provides a convenient way to perform HTTP PUT requests. It allow
     - [withHeaders](#withheaders)
     - [withResponseBodyFormat](#withresponsebodyformat)
     - [withAbilityAlias](#withabilityalias)
+    - [orSkipOnFail](#orskiponfail)
 
 ## Class Overview
 
@@ -92,4 +93,15 @@ public withAbilityAlias(alias: string): Put;
   - `alias` - The alias.
 - **Returns:** `Put` - Returns the current action.
 
+### orSkipOnFail
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get orSkipOnFail(): Put;
+```
+
+- **Description:** Allows to skip an action on fail.
+- **Returns:** `Put` - Returns the current action.
+
 [Back to overview](../../screenplay_elements.md)

docs/screenplay_elements/API/Questions/response.md

@@ -18,6 +18,8 @@ The `Response` class provides a flexible way to verify various aspects of an API
     - [body](#body)
     - [headers](#headers)
     - [beenReceivedWithin](#beenreceivedwithin)
+    - [withAbilityAlias](#withabilityalias)
+    - [failAsFalse](#failasfalse)
 
 ## Class Overview
 
@@ -104,4 +106,26 @@ public beenReceivedWithin(response: ResponseType, duration: number): Response;
   - `duration` - The expected duration (in milliseconds).
 - **Returns:** `Response` - The updated instance of the `Response` class.
 
+### withAbilityAlias
+
+```typescript
+public withAbilityAlias(alias: string): Response;
+```
+
+- **Description:** Defines the ability alias to be used during execution.
+- **Parameters:**
+  - `alias` - The alias.
+- **Returns:** `Response` - Returns the current question.
+
+### failAsFalse
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get failAsFalse(): Response;
+```
+
+- **Description:** Returns false instead of failing when exception occurrs.
+- **Returns:** `Response` - Returns the current question.
+
 [Back to overview](../../screenplay_elements.md)

docs/screenplay_elements/Web/Actions/add.md

@@ -13,6 +13,7 @@ The `Add` class is an action class in the Screenplay pattern designed for use wi
     - [performAs](#performas)
     - [cookies](#cookies)
     - [withAbilityAlias](#withabilityalias)
+    - [orSkipOnFail](#orskiponfail)
 
 ## Class Overview
 
@@ -51,4 +52,15 @@ public withAbilityAlias(alias: string): Add;
   - `alias` - The alias.
 - **Returns:** `Add` - Returns the current action.
 
+### orSkipOnFail
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get orSkipOnFail(): Add;
+```
+
+- **Description:** Allows to skip an action on fail.
+- **Returns:** `Add` - Returns the current action.
+
 [Back to overview](../../screenplay_elements.md)

docs/screenplay_elements/Web/Actions/check.md

@@ -14,6 +14,7 @@ The `Check` class is an action class in the Screenplay pattern designed for use
     - [element](#element)
     - [inFrame](#inframe)
     - [withAbilityAlias](#withabilityalias)
+    - [orSkipOnFail](#orskiponfail)
 
 ## Class Overview
 
@@ -64,4 +65,15 @@ public withAbilityAlias(alias: string): Check;
   - `alias` - The alias.
 - **Returns:** `Check` - Returns the current action.
 
+### orSkipOnFail
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get orSkipOnFail(): Check;
+```
+
+- **Description:** Allows to skip an action on fail.
+- **Returns:** `Check` - Returns the current action.
+
 [Back to overview](../../screenplay_elements.md)

docs/screenplay_elements/Web/Actions/clear.md

@@ -13,6 +13,7 @@ The `Clear` class is an action class in the Screenplay pattern designed for use
     - [performAs](#performas)
     - [cookies](#cookies)
     - [withAbilityAlias](#withabilityalias)
+    - [orSkipOnFail](#orskiponfail)
 
 ## Class Overview
 
@@ -49,4 +50,15 @@ public withAbilityAlias(alias: string): Clear;
   - `alias` - The alias.
 - **Returns:** `Clear` - Returns the current action.
 
+### orSkipOnFail
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get orSkipOnFail(): Clear;
+```
+
+- **Description:** Allows to skip an action on fail.
+- **Returns:** `Clear` - Returns the current action.
+
 [Back to overview](../../screenplay_elements.md)

docs/screenplay_elements/Web/Actions/click.md

@@ -14,6 +14,7 @@ The `Click` class is an action class in the Screenplay pattern designed for use
     - [on](#on)
     - [inFrame](#inframe)
     - [withAbilityAlias](#withabilityalias)
+    - [orSkipOnFail](#orskiponfail)
 
 ## Class Overview
 
@@ -64,4 +65,15 @@ public withAbilityAlias(alias: string): Click;
   - `alias` - The alias.
 - **Returns:** `Click` - Returns the current action.
 
+### orSkipOnFail
+
+*Introduced in: 1.6.0*
+
+```typescript
+public get orSkipOnFail(): Click;
+```
+
+- **Description:** Allows to skip an action on fail.
+- **Returns:** `Click` - Returns the current action.
+
 [Back to overview](../../screenplay_elements.md)