From 20912af115b32f1e929eedc62bff154782c8cc1f Mon Sep 17 00:00:00 2001
From: Jan Molak <1089173+jan-molak@users.noreply.github.com>
Date: Wed, 4 Oct 2023 12:31:24 +0100
Subject: [PATCH] Clarified the example scenarios. Thanks for the feedback,
 @muhqu

---
 spec/example.spec.ts | 64 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 58 insertions(+), 6 deletions(-)

diff --git a/spec/example.spec.ts b/spec/example.spec.ts
index d3aa6338e..ac0c04ac2 100644
--- a/spec/example.spec.ts
+++ b/spec/example.spec.ts
@@ -1,26 +1,78 @@
 import { Ensure, equals } from '@serenity-js/assertions';
 import { actorCalled } from '@serenity-js/core';
+import { By, Navigate, PageElement, Text } from '@serenity-js/web';
 import { describe, it } from 'mocha';
 
 import { GitHubStatus } from '../src/github';
 import { Homepage } from '../src/serenity';
 
+/**
+ * Serenity/JS Screenplay Pattern test scenarios use one or more actors to represent people and external systems
+ * interacting with the system under test.
+ *
+ * To design a test scenario, give each actor a series of tasks and interactions to perform
+ * and instruct them to answer questions about the state of the system under test
+ * to ensure that the answers meet the expected results.
+ *
+ * This example test file demonstrates several ways of writing test scenarios using the Screenplay Pattern.
+ *
+ * Learn more:
+ * - Serenity/JS Screenplay Pattern - https://serenity-js.org/handbook/design/screenplay-pattern/
+ * - Web Testing with Serenity/JS - https://serenity-js.org/handbook/web-testing/
+ * - API Testing with Serenity/JS - https://serenity-js.org/handbook/api-testing/
+ * - Serenity/JS web module - https://serenity-js.org/api/web/
+ * - Serenity/JS REST module - https://serenity-js.org/api/rest/
+ * - Serenity/JS assertions module - https://serenity-js.org/api/assertions/
+ */
 describe('Serenity/JS Website', () => {
 
-    it(`tells people what the framework can help them do`, async () => {
-
+    /**
+     * This is the most basic example of a Serenity/JS Screenplay Pattern test scenario.
+     *
+     * This scenario uses a single actor configured to perform a series of web-based interactions,
+     * and uses only the low-level abstractions provided by the Serenity/JS web module.
+     */
+    it('offers a web testing tutorial', async () => {
         await actorCalled('Alice').attemptsTo(
+            Navigate.to('https://serenity-js.org'),
+            Ensure.that(
+                Text.of(PageElement.located(By.id('cta-start-automating'))),
+                equals('Start automating 🚀')
+            ),
+        )
+    });
+
+    /**
+     * This is a more advanced example of a Serenity/JS Screenplay Pattern test scenario.
+     *
+     * This scenario uses two actors:
+     * - Apisitt, responsible for interacting with an API to check if the system is up and running before performing any UI checks
+     * - Wendy, responsible for interacting with the website to perform the actual acceptance test
+     *
+     * In this scenario, rather than list all the interactions in the test itself, we use:
+     * - API Actions Class Pattern to group tasks concerning interacting with the GitHubStatus API
+     * - Page Objects Pattern to group tasks and questions concerning interacting with the Serenity/JS Homepage
+     *
+     * Note that apart from strongly encouraging the Screenplay Pattern,
+     * Serenity/JS doesn't require you to organise your code in any particular way.
+     * This gives you the freedom to choose patterns and abstractions that work best for you, your team,
+     * and reflect the domain of your system under test.
+     */
+    it(`tells people what the framework can help them do`, async () => {
 
-            // You can use API interactions to ensure services are up and running before performing any UI checks,
-            // or to manage test data
+        // You can use API interactions to manage test data, or to ensure services are up and running before performing any UI checks.
+        // Since Serenity/JS website is deployed to GitHub Pages, before interacting with the website we ensure that GitHub is up and running.
+        await actorCalled('Apisitt').attemptsTo(
             GitHubStatus.ensureAllSystemsOperational(),
+        );
 
+        // Once we know the system is up and running, Wendy can proceed with the web-based scenario.
+        await actorCalled('Wendy').attemptsTo(
             Homepage.open(),
-
             Ensure.that(
                 Homepage.heroBannerHeadingText(),
                 equals('Enable collaborative test automation at any scale!')
             ),
-        )
+        );
     });
 });