Merge branch 'master' into renovate/axios-0.x

documentation/esdoc-external-docs-plugin/package.json

@@ -34,7 +34,7 @@
     "npm": "^6 || ^7 || ^8"
   },
   "dependencies": {
-    "glob": "^8.0.1",
+    "glob": "^8.0.3",
     "mkdirp": "^1.0.4",
     "rimraf": "^3.0.2"
   },

documentation/website/package.json

@@ -49,13 +49,13 @@
     "@serenity-js/serenity-bdd": "^2.0.0",
     "@serenity-js/webdriverio": "^2.0.0",
     "async": "^3.2.3",
-    "cheerio": "^1.0.0-rc.10",
-    "clean-css": "^5.3.0",
-    "glob": "^8.0.1",
+    "cheerio": "^1.0.0-rc.12",
+    "clean-css": "^5.3.1",
+    "glob": "^8.0.3",
     "handlebars": "^4.7.7",
     "jstransformer-handlebars": "^1.2.0",
-    "jstransformer-marked": "^1.1.0",
-    "metalsmith": "^2.4.2",
+    "jstransformer-marked": "^1.2.0",
+    "metalsmith": "^2.5.0",
     "metalsmith-autotoc": "^0.1.5",
     "metalsmith-browser-sync": "^1.1.1",
     "metalsmith-discover-helpers": "^0.1.1",

documentation/website/src/community/events-and-articles.md

@@ -4,78 +4,80 @@ layout: handbook.hbs
 ---
 # Serenity/JS events and articles
 
-If you've written an article, tutorial or a blog post, recorded a video, 
-or are planning to talk about Serenity/JS at a meetup or a conference, please 
+If you've written an article, tutorial or a blog post, recorded a video,
+or are planning to talk about Serenity/JS at a meetup or a conference, please
 [add it to the list below](https://github.com/serenity-js/serenity-js/edit/master/documentation/website/src/community/events-and-articles.md)
 to share the news with the community!
 
 ## Events
 
 - **2021-03-24, Aftertest online: Creating acceptance tests with Serenity/JS (in Spanish)**  
-[Crear tests de aceptación con Serenity/JS](https://www.aftertest.es/events/aftertest-online-automatizar-pruebas-con-serenity-js/) - [video](https://www.aftertest.es/video-aftertest-online-24-03/) | [slides](https://docs.google.com/presentation/d/1c3oz5QW5OM64506vYsRXZTEU2Nbh5wsU54_MoaBNaY4/edit#slide=id.gc1edf83f9b_0_307)  
-_by [Manuel Fidalgo](https://www.linkedin.com/in/manuelfidalgo/)_
+  [Crear tests de aceptación con Serenity/JS](https://www.aftertest.es/events/aftertest-online-automatizar-pruebas-con-serenity-js/) - [video](https://www.aftertest.es/video-aftertest-online-24-03/) | [slides](https://docs.google.com/presentation/d/1c3oz5QW5OM64506vYsRXZTEU2Nbh5wsU54_MoaBNaY4/edit#slide=id.gc1edf83f9b_0_307)  
+  _by [Manuel Fidalgo](https://www.linkedin.com/in/manuelfidalgo/)_
 
 - **2020-02-03, Automation Guild, online conference**  
-[Fullstack acceptance testing with Serenity/JS 2.0](https://guildconferences.com/conferences/automation-2020/)  
-_by [Jan Molak](https://janmolak.com)_  
+  [Fullstack acceptance testing with Serenity/JS 2.0](https://guildconferences.com/conferences/automation-2020/)  
+  _by [Jan Molak](https://janmolak.com)_
 
 - **2018-02-09, Cucumber Podcast**  
-[The Screenplay Pattern](https://cucumber.io/blog/podcast/screenplay-pattern-podcast/)  
-_with Aslak Hellesøy, John Smart, Jan Molak, Angie Jones, Nat Pryce, Matt Wynne and Steve Tooke_  
+  [The Screenplay Pattern](https://cucumber.io/blog/podcast/screenplay-pattern-podcast/)  
+  _with Aslak Hellesøy, John Smart, Jan Molak, Angie Jones, Nat Pryce, Matt Wynne and Steve Tooke_
 
 - **2017-11-08, Angular Connect, London, UK**   
-["Testing Angular apps. At scale"](https://www.angularconnect.com/2017/sessions/#s-675)   
-_by [Jan Molak](https://janmolak.com)_
+  ["Testing Angular apps. At scale"](https://www.angularconnect.com/2017/sessions/#s-675)   
+  _by [Jan Molak](https://janmolak.com)_
 
 - **2017-07-06, Agile on the beach, Penryn, Cornwall, UK**   
-["Testing modern web apps. At scale"](http://agileonthebeach.com/testing-modern-web-apps-scale-jan-molak-software-delivery-2017/)   
-_by [Jan Molak](https://janmolak.com)_
+  ["Testing modern web apps. At scale"](http://agileonthebeach.com/testing-modern-web-apps-scale-jan-molak-software-delivery-2017/)   
+  _by [Jan Molak](https://janmolak.com)_
 
 - **2017-05-11/12, Devoxx, London, UK**  
-["Testing modern web apps. At scale."](http://www.devoxx.co.uk/)   
-_by [Jan Molak](https://janmolak.com)_
+  ["Testing modern web apps. At scale."](http://www.devoxx.co.uk/)   
+  _by [Jan Molak](https://janmolak.com)_
 
 - **2017-02-16, Dublin Java User Group, Dublin, Ireland**  
-["From Scripts to Serenity - Refactoring test script spaghetti to patterns"](https://ti.to/tcube/dublin-java-user-group-february-2017)   
-_by [Jan Molak](https://janmolak.com)_
+  ["From Scripts to Serenity - Refactoring test script spaghetti to patterns"](https://ti.to/tcube/dublin-java-user-group-february-2017)   
+  _by [Jan Molak](https://janmolak.com)_
 
 - **2016-11-11, Devoxx, Antwerp, Belgium**     
-["Screenplay: The next stage in automated acceptance testing"](http://cfp.devoxx.be/2016/talk/BIC-3525/ScreenPlay:_the_next_stage_in_automated_acceptance_testing_)   
-_by [Jan Molak](https://janmolak.com) and [John Ferguson Smart](https://johnfergusonsmart.com)_
+  ["Screenplay: The next stage in automated acceptance testing"](http://cfp.devoxx.be/2016/talk/BIC-3525/ScreenPlay:_the_next_stage_in_automated_acceptance_testing_)   
+  _by [Jan Molak](https://janmolak.com) and [John Ferguson Smart](https://johnfergusonsmart.com)_
 
 - **2016-11-10, BDD Exchange, London, UK**  
-["Screenplay pattern - a SOLID alternative to Page Objects"](https://skillsmatter.com/skillscasts/9086-screenplay-pattern-a-solid-alternative-to-page-objects)  
-_by [Antony Marcano](https://ideas.riverglide.com)_
+  ["Screenplay pattern - a SOLID alternative to Page Objects"](https://skillsmatter.com/skillscasts/9086-screenplay-pattern-a-solid-alternative-to-page-objects)  
+  _by [Antony Marcano](https://ideas.riverglide.com)_
 
 - **2016-11-08, Devoxx, Antwerp, Belgium**  
-["Serenity/JS: Next generation acceptance testing for modern web apps"](http://cfp.devoxx.be/2016/talk/ICJ-3714/Serenity-JS:_next_generation_acceptance_testing_for_Angular-JS_in_TypeScript)   
-_by [Jan Molak](https://janmolak.com) and [John Ferguson Smart](https://johnfergusonsmart.com)_
- 
+  ["Serenity/JS: Next generation acceptance testing for modern web apps"](http://cfp.devoxx.be/2016/talk/ICJ-3714/Serenity-JS:_next_generation_acceptance_testing_for_Angular-JS_in_TypeScript)   
+  _by [Jan Molak](https://janmolak.com) and [John Ferguson Smart](https://johnfergusonsmart.com)_
+
 ## Articles
+- **["Lights, Camera... Screenplay! (A test automation pattern…)"](https://medium.com/adidoescode/lights-camera-screenplay-a-test-automation-pattern-f3af769af846)**   
+  _by [Rodrigo J Martin](https://www.linkedin.com/in/martinrodrigo/)_
+
 - **["Acting Out: Serenity-JS & The Screenplay Pattern"](https://suresoftlimited.com/2020/03/08/acting-out-serenity-js-the-screenplay-pattern)**   
-_by [Steven Williams](https://suresoftlimited.com)_
+  _by [Steven Williams](https://suresoftlimited.com)_
 
 - **["Create an Acceptance Test Framework from Scratch - Cucumber, Protractor, Serenity/JS and the Screenplay Pattern"](https://testifyqa.com/javascript-frameworks/#serenity-js)**   
-_by [Thomas Knee](https://testifyqa.com)_
+  _by [Thomas Knee](https://testifyqa.com)_
 
 - **["Smooth out the Sharp Angles of Protractor Testing - Helping failed assertions make a little bit more sense"](https://janmolak.com/expected-false-to-be-true-e920c512030d#.fhiow37y5)**   
-_by [Jan Molak](https://janmolak.com)_
+  _by [Jan Molak](https://janmolak.com)_
 
 - **["Introducing Serenity/JS - Next generation acceptance testing in JavaScript"](https://janmolak.com/introducing-serenity-js-c5565d295702#.oleggdi3g)**   
-_by [Jan Molak](https://janmolak.com) and [John Ferguson Smart](https://johnfergusonsmart.com)_
+  _by [Jan Molak](https://janmolak.com) and [John Ferguson Smart](https://johnfergusonsmart.com)_
 
 - **["Serenity BDD and the Screenplay Pattern - Designing SOLID Actors"](https://janmolak.com/serenity-bdd-and-the-screenplay-pattern-27819d0db780#.9druuq1js)**  
-_by [Jan Molak](https://janmolak.com)_
+  _by [Jan Molak](https://janmolak.com)_
 
 - **["From Acceptance Tests to User Guides - Living Documentation with Serenity BDD and the Screenplay Pattern"](https://janmolak.com/from-acceptance-tests-to-user-guides-71fc9756d341#.hsn52k1qs)**  
-_by [Jan Molak](https://janmolak.com) and [John Ferguson Smart](https://johnfergusonsmart.com)_
+  _by [Jan Molak](https://janmolak.com) and [John Ferguson Smart](https://johnfergusonsmart.com)_
 
 - **["Serenity with Jenkins 2.0"](https://janmolak.com/serenity-with-jenkins-2-0-7f4b8d48efe9#.udoxr07sn)**  
-_by [Jan Molak](https://janmolak.com)_
+  _by [Jan Molak](https://janmolak.com)_
 
 - **["Beyond Page Objects: Next Generation Test Automation with Serenity and the Screenplay Pattern"](https://www.infoq.com/articles/Beyond-Page-Objects-Test-Automation-Serenity-Screenplay)**    
-_by [John Ferguson Smart](https://johnfergusonsmart.com), [Antony Marcano](https://ideas.riverglide.com), [Andy Palmer](https://ideas.riverglide.com), [Jan Molak](https://janmolak.com)_
+  _by [John Ferguson Smart](https://johnfergusonsmart.com), [Antony Marcano](https://ideas.riverglide.com), [Andy Palmer](https://ideas.riverglide.com), [Jan Molak](https://janmolak.com)_
 
 - **["Page Objects Refactored: SOLID Steps to the Screenplay/Journey Pattern"](https://dzone.com/articles/page-objects-refactored-solid-steps-to-the-screenp)**  
-_by [Antony Marcano](https://ideas.riverglide.com), [Andy Palmer](https://ideas.riverglide.com), [Jan Molak](https://janmolak.com), [John Ferguson Smart](https://johnfergusonsmart.com)_  
-
+  _by [Antony Marcano](https://ideas.riverglide.com), [Andy Palmer](https://ideas.riverglide.com), [Jan Molak](https://janmolak.com), [John Ferguson Smart](https://johnfergusonsmart.com)_  

documentation/website/src/handbook/release-notes/serenity-js-3.md

@@ -109,7 +109,7 @@ For example, the below custom interaction to `ReloadPage` is **portable**, which
 import { Actor, Interaction } from '@serenity-js/core';
 import { BrowseTheWeb } from '@serenity-js/web'
 
-const ReloadPage = () => 
+const ReloadPage = () =>
     Interaction.where(`#actor reloads a page`, (actor: Actor) => {
         return BrowseTheWeb.as(actor).reloadPage();
     });
@@ -189,7 +189,7 @@ export class TodoList {
 }
 ```
 
-To see the new `PageElement` and `PageElements` APIs in actions, including using advanced element filters and mapping, 
+To see the new `PageElement` and `PageElements` APIs in action, including using advanced element filters and mapping,
 have a look at the [PageElements patterns spec](https://github.com/serenity-js/serenity-js/blob/main/integration/web-specs/spec/screenplay/models/PageElements.patterns.spec.ts).
 
 If you'd like to see a tutorial or screencast on this topic, let us know on Twitter!
@@ -360,6 +360,45 @@ actorCalled('Alice')
 
 The untyped flavour gives you access to `QuestionAdapter`s just like the typed version, however your text editor might not be able to provide you with as much support as it would if your notepad had been typed.
 
+## Waiting
+
+In Serenity/JS 2, interactions to `Wait.for` and `Wait.until` relied on browser-specific wait APIs, such as Protractor [`wait`](https://www.protractortest.org/#/api?view=webdriver.WebDriver.prototype.wait) or WebdriverIO [`waitUntil`](https://webdriver.io/docs/api/browser/waitUntil/).
+Since the interactions were specific to browser integration tools, they'd also come as part of `@serenity-js/protractor` or `@serenity-js/webdriverio` modules.
+
+In Serenity/JS 3, interactions to `Wait` **don't rely on any browser integration tool** and are, in fact, completely browser-independent.
+What this means in practice is that you can use `Wait` for both browser and API tests.
+
+Since `Wait` is no longer tied to the browser, it's also been moved to `@serenity-js/core`:
+
+```diff
+import { actorCalled, Duration } from '@serenity-js/core';
+- import { Wait } from '@serenity-js/protractor';
+- import { Wait } from '@serenity-js/webdriverio';
++ import { Wait } from '@serenity-js/core';
+
+actorCalled('Alice').attemptsTo(
+    Wait.for(Duration.ofSeconds(1)),
+
+    Wait.until(someQuestion, someExpectation)
+        .pollingEvery(Duration.ofMilliseconds(10)),
+
+    Wait.upTo(Duration.ofSeconds(5)
+        .until(someQuestion, someExpectation)
+        .pollingEvery(Duration.ofMilliseconds(10)),
+)
+```
+
+Additionally, `Wait.until` has also received a new API allowing you to configure its polling interval (500ms by default):
+
+```typescript
+import { actorCalled, Duration, Wait } from '@serenity-js/core';
+
+actorCalled('Alice').attemptsTo(
+    Wait.until(someQuestion, someExpectation)
+        .pollingEvery(Duration.ofMilliseconds(10)),
+)
+```
+
 ## `@serenity-js/assertions`
 
 ### `property` removed
@@ -400,9 +439,9 @@ Ensure.that(User().toUpperCase().slice(1, 4), equals('JAN'))
 
 ## `@serenity-js/rest`
 
-### `DynamicRecord<AxiosRequestConfig>` in HTTP requests
+### `Answerable<WithAnswerableProperties<AxiosRequestConfig>>` in HTTP requests
 
-All HTTP requests now accept dynamic `DynamicRecord<AxiosRequestConfig>`, which means you can now specify additional
+All HTTP requests now accept `Answerable<WithAnswerableProperties<AxiosRequestConfig>>`, which means you can now specify additional
 HTTP request configuration using a configuration object with nested `Question`s, `QuestionAdapter`s and `Promise`s.
 
 For example:
@@ -445,9 +484,10 @@ actorCalled('René').attemptsTo(
 
 ## `@serenity-js/core`
 
-### Screenplay-style `Dictionary<T>`
+### Screenplay-style dictionaries with `Question.fromObject`
 
-A new Screenplay-style data structure, `Dictionary<T>` will help you convert and merge plain JavaScript objects with nested [`Answerable`s](/modules/core/typedef/index.html#static-typedef-Answerable%3CT%3E) into a `QuestionAdapter<T>`.
+A new Screenplay-style data structure, `Answerable<WithAnswerableProperties<Source_Type>>` will help you convert
+and merge plain JavaScript objects with nested [`Answerable`s](/modules/core/typedef/index.html#static-typedef-Answerable%3CT%3E) into a `QuestionAdapter<T>`.
 
 For example:
 
@@ -465,7 +505,7 @@ actorCalled('René').attemptsTo(
     Send.a(
         PostRequest.to('/products')
             .with(
-                Dictionary.of<AddProductRequestData>({
+                Question.fromObject<AddProductRequestData>({
                     name:       Text.of(someElement),
                     quantity:   Text.of(someOtherElement).as(Number)
                 })
@@ -474,10 +514,10 @@ actorCalled('René').attemptsTo(
 );
 ```
 
-To merge several objects, pass them to `Dictionary.of` as per the example below:
+To merge several objects, pass them to `Question.fromObject` as per the example below:
 
 ```typescript
-Dictionary.of<AddProductRequestData>(  
+Question.fromObject<AddProductRequestData>(  
     // initial values
     { name: 'unknown', quantity: 0 },
     // overrides
@@ -488,8 +528,10 @@ Dictionary.of<AddProductRequestData>(
 ```
 
 Note that in the above code sample, the first object contains values for all the fields
-required by AddProductRequestData interface. If not all the fields are required, make sure
-to mark them as [optional](https://www.typescriptlang.org/docs/handbook/interfaces.html#optional-properties).
+required by `AddProductRequestData` interface.
+
+If not all the fields are required, make sure to mark them
+as [optional](https://www.typescriptlang.org/docs/handbook/interfaces.html#optional-properties).
 
 For example:
 
@@ -502,7 +544,6 @@ interface AddProductRequestData {
 
 ## More coming soon!
 
-
 <div class="pro-tip">
     <div class="icon"><i class="fab fa-github"></i></div>
     <div class="text">

integration/webdriverio-cucumber/package.json

@@ -41,7 +41,7 @@
     "@wdio/mocha-framework": "^7.19.7",
     "@wdio/reporter": "^7.19.7",
     "@wdio/spec-reporter": "^7.19.7",
-    "chromedriver": "^101.0.0",
+    "chromedriver": "^103.0.0",
     "cli-table3": "^0.6.2",
     "colors": "1.4.0",
     "webdriverio": "^7.19.7",