Merge d000f46 into 27eb0ec

integration/playwright-test/spec/failing_scenarios.spec.ts

@@ -103,7 +103,7 @@ describe('@serenity-js/playwright-test', function () {
 
                         expect(error.name).to.equal('AssertionError');
                         expect(outcome.error.message).to.match(new RegExp(trimmed`
-                            | Expected 'Hello' to equal 'Hola'
+                            | Expected "Hello" to equal "Hola"
                             |
                             | Expectation: equals\\('Hola'\\)
                             |

integration/protractor-jasmine/spec/screenplay.spec.ts

@@ -32,9 +32,9 @@ describe('@serenity-js/jasmine', function () {
                     .next(SceneTagged,              event => expect(event.tag).to.equal(new FeatureTag('Jasmine')))
                     .next(TestRunnerDetected,       event => expect(event.name).to.equal(new Name('Jasmine')))
                     .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Jasmine disables synchronisation with Angular`)))
-                    .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Jasmine navigates to 'chrome://version/'`)))
-                    .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Jasmine navigates to 'chrome://accessibility/'`)))
-                    .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Jasmine navigates to 'chrome://chrome-urls/'`)))
+                    .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Jasmine navigates to "chrome://version/"`)))
+                    .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Jasmine navigates to "chrome://accessibility/"`)))
+                    .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Jasmine navigates to "chrome://chrome-urls/"`)))
 
                     .next(SceneFinishes,            event => {
                         expect(event.sceneId).to.equal(currentSceneId);

integration/protractor-mocha/spec/screenplay.spec.ts

@@ -48,9 +48,9 @@ describe('@serenity-js/mocha', function () {
                 .next(SceneTagged,              event => expect(event.tag).to.equal(new FeatureTag('Mocha')))
                 .next(TestRunnerDetected,       event => expect(event.name).to.equal(new Name('Mocha')))
                 .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Mocha disables synchronisation with Angular`)))
-                .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Mocha navigates to 'chrome://version/'`)))
-                .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Mocha navigates to 'chrome://accessibility/'`)))
-                .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Mocha navigates to 'chrome://chrome-urls/'`)))
+                .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Mocha navigates to "chrome://version/"`)))
+                .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Mocha navigates to "chrome://accessibility/"`)))
+                .next(InteractionStarts,        event => expect(event.details.name).to.equal(new Name(`Mocha navigates to "chrome://chrome-urls/"`)))
 
                 .next(SceneFinishes,            event => {
                     expect(event.sceneId).to.equal(currentSceneId);

integration/web-specs/spec/screenplay/interactions/Enter.spec.ts

@@ -2,8 +2,9 @@ import 'mocha';
 
 import { expect } from '@integration/testing-tools';
 import { Ensure, equals } from '@serenity-js/assertions';
-import { actorCalled, Masked } from '@serenity-js/core';
+import { actorCalled, Masked, Question } from '@serenity-js/core';
 import { By, Enter, Navigate, PageElement, Value } from '@serenity-js/web';
+import { given } from 'mocha-testdata';
 
 /** @test {Enter} */
 describe('Enter', () => {
@@ -35,23 +36,149 @@ describe('Enter', () => {
             Ensure.that(Value.of(Form.field), equals('123')),
         ));
 
-    /** @test {Enter#toString} */
-    it('provides a sensible description of the interaction being performed', () => {
-        expect(Enter.theValue(actorCalled('Bernie').name).into(Form.field).toString())
-            .to.equal(`#actor enters 'Bernie' into the name field`);
-    });
-
-    it('provides a sensible and masked description of the interaction being performed', () => {
-        expect(Enter.theValue(Masked.valueOf(actorCalled('Bernie').name)).into(Form.field).toString())
-            .to.equal(`#actor enters '[a masked value]' into the name field`);
-    });
-
     it('correctly detects its invocation location', () => {
         const activity = Enter.theValue(actorCalled('Bernie').name).into(Form.field);
         const location = activity.instantiationLocation();
 
         expect(location.path.basename()).to.equal('Enter.spec.ts');
-        expect(location.line).to.equal(50);
+        expect(location.line).to.equal(40);
         expect(location.column).to.equal(69);
     });
+
+    describe('when generating a description', () => {
+
+        describe('toString', () => {
+
+            given([
+                { description: 'string',    value: 'some text',                                 expected: '#actor enters "some text" into the name field' },
+                { description: 'number',    value: 42,                                          expected: '#actor enters 42 into the name field' },
+                { description: 'promise',   value: Promise.resolve('text'),                     expected: '#actor enters Promise into the name field' },
+                { description: 'Question',  value: Question.about('value', actor => 'text'),    expected: '#actor enters value into the name field' },
+            ]).
+            it('includes a description of the parameter', ({ value, expected }) => {
+                const enter = Enter.theValue(value)
+                    .into(Form.field);
+
+                expect(enter.toString()).to.equal(expected);
+            });
+
+            given([
+                {
+                    description: 'string[]',
+                    value: [ 'some', 'text' ],
+                    expected: '#actor enters [ "some", "text" ] into the name field'
+                },
+                {
+                    description: 'number[]',
+                    value: [ 4, 2 ],
+                    expected: '#actor enters [ 4, 2 ] into the name field'
+                },
+                {
+                    description: 'promise[]',
+                    value: [ Promise.resolve('text'), Promise.resolve(1) ],
+                    expected: '#actor enters [ Promise, Promise ] into the name field'
+                },
+                {
+                    description: 'Question[]',
+                    value: [
+                        Question.about('value1', actor => 'text'),
+                        Question.about('value2', actor => 'text')
+                    ],
+                    expected: '#actor enters [ value1, value2 ] into the name field'
+                },
+            ]).
+            it('includes a description of multiple parameters', ({ value, expected }) => {
+                const enter = Enter.theValue(...value)
+                    .into(Form.field);
+
+                expect(enter.toString()).to.equal(expected);
+            });
+
+            it('masks the parameter when required', () => {
+                const enter = Enter.theValue(Masked.valueOf(actorCalled('Bernie').name))
+                    .into(Form.field);
+
+                expect(enter.toString())
+                    .to.equal(`#actor enters [a masked value] into the name field`);
+            });
+        });
+
+        describe('describedBy', () => {
+            given([
+                {
+                    description: 'string',
+                    value: 'some text',
+                    expected: 'Bernie enters "some text" into the name field'
+                },
+                {
+                    description: 'number',
+                    value: 42,
+                    expected: 'Bernie enters 42 into the name field'
+                },
+                {
+                    description: 'promise',
+                    value: Promise.resolve('text'),
+                    expected: 'Bernie enters "text" into the name field'
+                },
+                {
+                    description: 'Question',
+                    value: Question.about('value', actor => 'text').describedAs(Question.formattedValue()),
+                    expected: 'Bernie enters "text" into the name field'
+                },
+            ]).
+            it('includes the value of the parameter', async ({ value, expected }) => {
+                const enter = Enter.theValue(value)
+                    .into(Form.field);
+
+                const description = await enter.describedBy(actorCalled('Bernie'))
+
+                expect(description).to.equal(expected);
+            });
+
+            given([
+                {
+                    description: 'string[]',
+                    value: [ 'some', 'text' ],
+                    expected: 'Bernie enters [ "some", "text" ] into the name field'
+                },
+                {
+                    description: 'number[]',
+                    value: [ 4, 2 ],
+                    expected: 'Bernie enters [ 4, 2 ] into the name field'
+                },
+                {
+                    description: 'promise[]',
+                    value: [ Promise.resolve('text'), Promise.resolve(1) ],
+                    expected: 'Bernie enters [ "text", 1 ] into the name field'
+                },
+                {
+                    description: 'Question[]',
+                    value: [
+                        Question.about('value1', actor => 'text1').describedAs(Question.formattedValue()),
+                        Question.about('value2', actor => 'text2'),
+                        Question.about('value3', actor => 42).describedAs(Question.formattedValue()),
+                    ],
+                    expected: 'Bernie enters [ "text1", value2, 42 ] into the name field'
+                },
+            ]).
+            it('includes a description of multiple parameters', async ({ value, expected }) => {
+                const enter = Enter.theValue(...value)
+                    .into(Form.field);
+
+                const description = await enter.describedBy(actorCalled('Bernie'))
+
+                expect(description).to.equal(expected);
+            });
+
+            it('masks the parameter when required', async () => {
+                const enter = Enter.theValue(Masked.valueOf(actorCalled('Bernie').name))
+                    .into(Form.field);
+
+                const description = await enter.describedBy(actorCalled('Bernie'))
+
+                expect(description)
+                    .to.equal(`Bernie enters [a masked value] into the name field`);
+            });
+        });
+    });
 });

integration/web-specs/spec/screenplay/interactions/Navigate.spec.ts

@@ -27,7 +27,7 @@ describe('Navigate', () => {
 
         it('provides a sensible description of the interaction being performed', () => {
             expect(Navigate.to(`https://serenity-js.org`).toString())
-                .to.equal(`#actor navigates to 'https://serenity-js.org'`);
+                .to.equal(`#actor navigates to "https://serenity-js.org"`);
         });
 
         it('correctly detects its invocation location', () => {

integration/web-specs/spec/screenplay/interactions/Select.spec.ts

@@ -172,7 +172,7 @@ describe('Select', () => {
 
         it('provides a sensible description of Select.value()', () => {
             expect(Select.value('FR').from(SingleSelectPage.selector).toString())
-                .to.equal(`#actor selects value 'FR' from the country selector`);
+                .to.equal(`#actor selects value "FR" from the country selector`);
         });
 
         it('provides a sensible description of Selected.valueOf', () => {
@@ -182,7 +182,7 @@ describe('Select', () => {
 
         it('provides a sensible description of Select.option()', () => {
             expect(Select.option('France').from(SingleSelectPage.selector).toString())
-                .to.equal(`#actor selects 'France' from the country selector`);
+                .to.equal(`#actor selects "France" from the country selector`);
         });
 
         it('provides a sensible description of Selected.optionIn()', () => {

integration/web-specs/spec/screenplay/interactions/TakeScreenshot.spec.ts

@@ -43,7 +43,7 @@ describe('TakeScreenshot', () => {
         }));
 
     it('provides a sensible description of the interaction being performed', () => {
-        expect(TakeScreenshot.of('the page').toString()).to.equal(`#actor takes a screenshot of 'the page'`);
+        expect(TakeScreenshot.of('the page').toString()).to.equal(`#actor takes a screenshot of "the page"`);
     });
 
     it('correctly detects its invocation location', () => {

integration/web-specs/spec/screenplay/interactions/Wait.spec.ts

@@ -99,7 +99,7 @@ describe('Wait', () => {
             )).to.be.rejected.then((error: AssertionError) => {
                 expect(error).to.be.instanceOf(AssertionError);
                 expect(error.message).to.match(new RegExp(trimmed`
-                    | Timeout of 2s has expired while waiting for the text of the header to equal 'Ready!'
+                    | Timeout of 2s has expired while waiting for the text of the header to equal "Ready!"
                     |
                     | Expectation: equals\\('Ready!'\\)
                     |
@@ -111,7 +111,7 @@ describe('Wait', () => {
 
         it('provides a sensible description of the interaction being performed', () => {
             expect(Wait.upTo(Duration.ofSeconds(1)).until(Text.of(status()), equals('Ready!')).toString())
-                .to.equal(`#actor waits until the text of the header does equal 'Ready!'`);
+                .to.equal(`#actor waits until the text of the header does equal "Ready!"`);
         });
     });
 });

integration/web-specs/spec/screenplay/interactions/execute-script/ExecuteAsynchronousScript.spec.ts

@@ -239,7 +239,7 @@ describe('ExecuteAsynchronousScript', function () {
 
         expect(ExecuteScript.async(`arguments[arguments.length - 1]();`)
             .withArguments(Promise.resolve('arg1'), 'arg2', arg3).toString(),
-        ).to.equal(`#actor executes an asynchronous script with arguments: [ <<Promise>>, 'arg2', <<arg number 3>> ]`);
+        ).to.equal(`#actor executes an asynchronous script with arguments: [ Promise, "arg2", arg number 3 ]`);
     });
 
     it('complains if the script has failed', () =>

integration/web-specs/spec/screenplay/interactions/execute-script/ExecuteScriptFromUrl.spec.ts

@@ -70,6 +70,6 @@ describe('ExecuteScriptFromUrl', function () {
 
     it('provides a sensible description of the interaction being performed', () => {
         expect(ExecuteScript.from('https://localhost/script.js').toString())
-            .to.equal(`#actor executes a script from 'https://localhost/script.js'`);
+            .to.equal(`#actor executes a script from "https://localhost/script.js"`);
     });
 });

integration/web-specs/spec/screenplay/interactions/execute-script/ExecuteSynchronousScript.spec.ts

@@ -183,7 +183,7 @@ describe('ExecuteSynchronousScript', function () {
 
         expect(ExecuteScript.sync(`console.log('hello world');`)
             .withArguments(Promise.resolve('arg1'), 'arg2', arg3).toString(),
-        ).to.equal(`#actor executes a synchronous script with arguments: [ <<Promise>>, 'arg2', <<arg number 3>> ]`);
+        ).to.equal(`#actor executes a synchronous script with arguments: [ Promise, "arg2", arg number 3 ]`);
     });
 
     it('complains if the script has failed', () =>

integration/web-specs/spec/screenplay/models/Page.spec.ts

@@ -114,7 +114,7 @@ describe('Page', () => {
             it('complains if the page the actor wants to switch to does not exist', async () =>
                 expect(actorCalled('Bernie').attemptsTo(
                     Ensure.that(Page.whichName(startsWith('invalid')).title(), equals(`this won't pass`)),
-                )).to.be.rejectedWith(LogicError, `Couldn't find a page which name does start with 'invalid'`),
+                )).to.be.rejectedWith(LogicError, `Couldn't find a page which name does start with "invalid"`),
             );
         });
 
@@ -303,7 +303,7 @@ describe('Page', () => {
             it('returns a human-readable description of the page', () => {
                 const description = Page.whichName(equals('pop-up')).toString();
 
-                expect(description).to.equal(`page which name does equal 'pop-up'`);
+                expect(description).to.equal(`page which name does equal "pop-up"`);
             });
         });
 
@@ -314,7 +314,7 @@ describe('Page', () => {
             it('returns a human-readable description of the page', () => {
                 const description = Page.whichTitle(equals('Serenity/JS Website')).toString();
 
-                expect(description).to.equal(`page which title does equal 'Serenity/JS Website'`);
+                expect(description).to.equal(`page which title does equal "Serenity/JS Website"`);
             });
         });
 
@@ -325,7 +325,7 @@ describe('Page', () => {
             it('returns a human-readable description of the page', () => {
                 const description = Page.whichUrl(endsWith('/articles/example.html')).toString();
 
-                expect(description).to.equal(`page which URL does end with '/articles/example.html'`);
+                expect(description).to.equal(`page which URL does end with "/articles/example.html"`);
             });
         });
     });

integration/web-specs/spec/screenplay/models/PageElements.patterns.spec.ts

@@ -352,7 +352,7 @@ describe('PageElements', () => {
                 ).toString();
 
                 expect(description).to.equal(
-                    `the text of heading of the last of containers of filter pattern with mapping section where the text of list items does contain 'coffee'`
+                    `the text of heading of the last of containers of filter pattern with mapping section where the text of list items does contain "coffee"`
                 );
             });
         });