@serenity-js/protractor 3.0.0-rc.9 → 3.0.1

package/src/adapter/Config.ts

@@ -2,18 +2,19 @@ import { SerenityConfig } from '@serenity-js/core';
 import { Config as ProtractorConfig } from 'protractor';
 
 /**
- * @desc
- *  Protractor configuration object with an additional
- *  section to configure the Serenity/JS framework.
+ * Protractor configuration object with an additional
+ * section to configure the Serenity/JS framework.
  *
- * @public
- * @interface
+ * ## Learn more
+ * - [Protractor config](https://github.com/angular/protractor/blob/master/lib/config.ts)
+ * - {@apilink SerenityConfig}
+ * - {@apilink configure}
  *
- * @see {@link @serenity-js/core~SerenityConfig}
- *
- * @see https://github.com/angular/protractor/blob/master/lib/config.ts
- * @see {@link @serenity-js/core~configure}
+ * @group Configuration
  */
 export interface Config extends ProtractorConfig {
+    /**
+     * See {@apilink SerenityConfig}
+     */
     serenity: SerenityConfig & { runner?: string };
 }

package/src/adapter/ProtractorFrameworkAdapter.ts

@@ -1,13 +1,17 @@
-import { ArtifactArchiver, Serenity } from '@serenity-js/core';
-import { isPlainObject } from 'is-plain-object'; // fails when using default import
+import { AnsiDiffFormatter, ArtifactArchiver, Cast, Serenity } from '@serenity-js/core';
 import { protractor, Runner } from 'protractor';
-import deepmerge = require('deepmerge');
-const querySelectorShadowDomPlugin = require('query-selector-shadow-dom/plugins/protractor');   // eslint-disable-line @typescript-eslint/no-var-requires
+import { isRecord } from 'tiny-types/lib/objects';
 
 import { BrowserDetector, StandardisedCapabilities } from './browser-detector';
 import { Config } from './Config';
 import { ProtractorReport, ProtractorReporter } from './reporter';
 import { TestRunnerDetector } from './runner';
+import deepmerge = require('deepmerge');
+import { TakeNotes } from '@serenity-js/core';
+
+import { BrowseTheWebWithProtractor } from '../screenplay';
+
+const querySelectorShadowDomPlugin = require('query-selector-shadow-dom/plugins/protractor');   // eslint-disable-line @typescript-eslint/no-var-requires
 
 /**
  * @private
@@ -21,10 +25,8 @@ export class ProtractorFrameworkAdapter {
     }
 
     /**
-     * @param {string[]} specs
+     * @param specs
      *  Paths to spec files
-     *
-     * @return {Promise<ProtractorReport>}
      */
     run(specs: string[]): Promise<ProtractorReport> {
 
@@ -36,12 +38,16 @@ export class ProtractorFrameworkAdapter {
         const reporter  = new ProtractorReporter(this.protractorRunner, runner.successThreshold());
 
         const config    = deepmerge<Config>(this.defaultConfig(), this.protractorRunner.getConfig(), {
-            isMergeableObject: isPlainObject,
+            isMergeableObject: isRecord,
         });
 
         this.serenity.configure({
             cueTimeout:     config.serenity.cueTimeout,
-            actors:         config.serenity.actors,
+            actors:         config.serenity.actors || Cast.where(actor => actor.whoCan(
+                BrowseTheWebWithProtractor.using(protractor.browser),
+                TakeNotes.usingAnEmptyNotepad(),
+            )),
+            diffFormatter:  config.serenity.diffFormatter ?? new AnsiDiffFormatter(),
             crew:           [
                 BrowserDetector.with(StandardisedCapabilities.of(() => protractor.browser)),
                 ...config.serenity.crew,
@@ -53,7 +59,7 @@ export class ProtractorFrameworkAdapter {
             .then(() => this.protractorRunner.runTestPreparer(TestRunnerDetector.protractorCliOptions()))
             .then(() => runner.load(specs))
             .then(() => runner.run())
-            .then(() => Promise.resolve((config.onComplete || noop)()))
+            .then(() => (config.onComplete || noop)())
             .then(() => reporter.report());
     }
 

package/src/adapter/browser-detector/BrowserDetector.ts

@@ -1,6 +1,6 @@
 import { Stage } from '@serenity-js/core';
 import { AsyncOperationAttempted, AsyncOperationCompleted, DomainEvent, SceneStarts, SceneTagged } from '@serenity-js/core/lib/events';
-import { BrowserTag, CorrelationId, Description, PlatformTag } from '@serenity-js/core/lib/model';
+import { BrowserTag, CorrelationId, Description, Name, PlatformTag } from '@serenity-js/core/lib/model';
 import { StageCrewMember } from '@serenity-js/core/lib/stage';
 
 import { StandardisedCapabilities } from './StandardisedCapabilities';
@@ -33,7 +33,8 @@ export class BrowserDetector implements StageCrewMember {
             const id = CorrelationId.create();
 
             this.stage.announce(new AsyncOperationAttempted(
-                new Description(`[${ this.constructor.name }] Detecting web browser details...`),
+                new Name(this.constructor.name),
+                new Description(`Detecting web browser details...`),
                 id,
                 this.stage.currentTime(),
             ));
@@ -59,7 +60,6 @@ export class BrowserDetector implements StageCrewMember {
                 ));
 
                 this.stage.announce(new AsyncOperationCompleted(
-                    new Description(`[${ this.constructor.name }] Detected web browser details`),
                     id,
                     this.stage.currentTime(),
                 ));

package/src/adapter/browser-detector/StandardisedCapabilities.ts

@@ -11,34 +11,33 @@ export class StandardisedCapabilities {
     constructor(private currentBrowser: () => ProtractorBrowser) {
     }
 
-    browserName(): PromiseLike<string> {
+    browserName(): Promise<string | undefined> {
         return this.get(
             caps => caps.get('browserName'),
         );
     }
 
-    browserVersion(): PromiseLike<string> {
-        return this.get(
+    async browserVersion(): Promise<string | undefined> {
+        const version = await this.get(
             caps => caps.get('version'),
             caps => caps.get('browserVersion'),
             caps => caps.has('deviceManufacturer') && caps.has('deviceModel')
                 ? `${ caps.get('deviceManufacturer') } ${ caps.get('deviceModel') }`
                 : undefined,
             caps => caps.has('mobile') && caps.get('mobile').version,
-        ).
-        then(version =>
-            this.get(
-                caps => !! caps.get('mobileEmulationEnabled') && '(mobile emulation)',
-            ).then(suffix =>
-                [
-                    version,
-                    suffix,
-                ].filter(_ => !!_).join(' '),
-            ),
         );
+
+        const suffix = await this.get(
+            caps => !! caps.get('mobileEmulationEnabled') && '(mobile emulation)',
+        );
+
+        return [
+            version,
+            suffix,
+        ].filter(_ => !!_).join(' ');
     }
 
-    platformName(): PromiseLike<string> {
+    platformName(): Promise<string | undefined> {
         return this.get(
             caps => (!! caps.get('platformName') && ! /any/i.test(caps.get('platformName')))
                 ? caps.get('platformName')
@@ -46,21 +45,22 @@ export class StandardisedCapabilities {
         );
     }
 
-    platformVersion(): PromiseLike<string> {
+    platformVersion(): Promise<string | undefined> {
         return this.get(
             caps => caps.get('platformVersion'),
         );
     }
 
-    private get(...fetchers: Array<(capabilities: Capabilities) => string>): PromiseLike<string> {
-        return this.currentBrowser().getCapabilities().then(caps => {
-            for (const fetcher of fetchers) {
-                const result = fetcher(caps);
-                if (result) {
-                    return result;
-                }
+    private async get(...fetchers: Array<(capabilities: Capabilities) => string>): Promise<string | undefined> {
+        const capabilities = await this.currentBrowser().getCapabilities();
+
+        for (const fetcher of fetchers) {
+            const result = fetcher(capabilities);
+            if (result) {
+                return result;
             }
-            return undefined;   // eslint-disable-line unicorn/no-useless-undefined
-        });
+        }
+
+        return undefined;   // eslint-disable-line unicorn/no-useless-undefined
     }
 }

package/src/adapter/index.ts

@@ -1,3 +1,4 @@
+export * from './Config';
 export * from './ProtractorFrameworkAdapter';
 export * from './run';
 export * from './runner';

package/src/adapter/reporter/ProtractorReport.ts

@@ -1,13 +1,11 @@
 import { SpecResult } from 'protractor/built/plugins';
 
 /**
- * @desc
- *  A JSON object which needs to be returned to Protractor when {@link ProtractorFrameworkAdapter}
- *  is done with executing the test scenarios.
+ * A JSON object which needs to be returned to Protractor when {@apilink ProtractorFrameworkAdapter}
+ * is done with executing the test scenarios.
  *
- * @see https://github.com/angular/protractor/blob/master/lib/frameworks/README.md
- *
- * @private
+ * ## Learn more
+ * - [Protractor Custom Frameworks Readme](https://github.com/angular/protractor/blob/master/lib/frameworks/README.md)
  */
 export interface ProtractorReport {
     /**

package/src/adapter/reporter/ProtractorReporter.ts

@@ -1,6 +1,6 @@
-import { Stage } from '@serenity-js/core';
+import { Stage, Timestamp } from '@serenity-js/core';
 import { AsyncOperationAttempted, AsyncOperationCompleted, AsyncOperationFailed, DomainEvent, SceneFinished, SceneFinishes, SceneStarts } from '@serenity-js/core/lib/events';
-import { CorrelationId, Description, ExecutionSkipped, Outcome, ProblemIndication, Timestamp } from '@serenity-js/core/lib/model';
+import { CorrelationId, Description, ExecutionSkipped, Name, Outcome, ProblemIndication } from '@serenity-js/core/lib/model';
 import { StageCrewMember } from '@serenity-js/core/lib/stage';
 import { Runner } from 'protractor';
 
@@ -85,29 +85,29 @@ export class ProtractorReporter implements StageCrewMember {
         });
     }
 
-    private afterEach(): PromiseLike<void> {
+    private async afterEach(): Promise<void> {
         if (! this.runner.afterEach) {
-            return Promise.resolve();
+            return;
         }
 
         const id = CorrelationId.create();
 
         this.stage.announce(new AsyncOperationAttempted(
-            new Description(`[${ this.constructor.name }] Invoking ProtractorRunner.afterEach...`),
+            new Name(this.constructor.name),
+            new Description(`Invoking ProtractorRunner.afterEach...`),
             id,
             this.stage.currentTime(),
         ));
 
-        return Promise.resolve(this.runner.afterEach() as PromiseLike<void> | undefined)
-            .then(
-                () =>
-                    this.stage.announce(new AsyncOperationCompleted(
-                        new Description(`[${ this.constructor.name }] ProtractorRunner.afterEach succeeded`),
-                        id,
-                        this.stage.currentTime(),
-                    )),
-                error =>
-                    this.stage.announce(new AsyncOperationFailed(error, id, this.stage.currentTime())),
-            );
+        try {
+            await this.runner.afterEach();
+
+            this.stage.announce(new AsyncOperationCompleted(
+                id,
+                this.stage.currentTime(),
+            ));
+        } catch (error) {
+            this.stage.announce(new AsyncOperationFailed(error, id, this.stage.currentTime()));
+        }
     }
 }

package/src/adapter/run.ts

@@ -9,11 +9,13 @@ import { ProtractorReport } from './reporter';
 import { TestRunnerDetector, TestRunnerLoader } from './runner';
 
 /**
- * @param {protractor~Runner} runner
- * @param {string[]} specs
- * @returns {Promise<ProtractorReport>}
+ * ## Learn more
+ * - [Protractor framework adapters](https://github.com/angular/protractor/blob/master/lib/frameworks/README.md#framework-adapters-for-protractor)
  *
- * @see https://github.com/angular/protractor/blob/master/lib/frameworks/README.md#framework-adapters-for-protractor
+ * @param runner
+ * @param specs
+ *
+ * @group Integration
  */
 export function run(runner: Runner, specs: string[]): Promise<ProtractorReport> {
     const cwd = Path.from(runner.getConfig().configDir);

package/src/adapter/runner/CucumberAdapterConfig.ts

@@ -1,21 +1,16 @@
 /**
- * @public
- * @interface
+ * @group Integration
  */
 export interface CucumberAdapterConfig {
+
     /**
-     * @desc
-     *  Instruct Serenity/JS Cucumber Adapter to take over the stdout output of native Cucumber reporters to prevent them from clobbering the log
-     *
-     * @type {boolean}
+     * Instruct Serenity/JS Cucumber Adapter to take over the `stdout` output
+     * of native Cucumber reporters to prevent them from clobbering the log.
      */
     useStandardOutput: boolean;
 
     /**
-     * @desc
-     *  Add `runnerId` to names of output files produced by native Cucumber.js formatters
-     *
-     * @type {boolean}
+     * Add `runnerId` to names of output files produced by native Cucumber.js formatters
      */
     uniqueFormatterOutputs: boolean;
 }

package/src/adapter/runner/TestRunnerDetector.ts

@@ -1,14 +1,13 @@
-import { TestRunnerAdapter } from '@serenity-js/core/lib/io';
+import { TestRunnerAdapter } from '@serenity-js/core/lib/adapter';
 import { Config as ProtractorConfig } from 'protractor';
 
 import { TestRunnerLoader } from './TestRunnerLoader';
 
 /**
- * @desc
- *  Detects the {@link @serenity-js/core/lib/io~TestRunnerAdapter} to use,
- *  based on Protractor configuration.
+ * Detects the {@apilink TestRunnerAdapter} to use,
+ * based on Protractor configuration.
  *
- * @public
+ * @group Integration
  */
 export class TestRunnerDetector {
 
@@ -24,16 +23,9 @@ export class TestRunnerDetector {
         ];
     }
 
-    /**
-     * @param {TestRunnerLoader} testRunnerLoader
-     */
     constructor(private readonly testRunnerLoader: TestRunnerLoader) {
     }
 
-    /**
-     * @param {protractor~ProtractorConfig} config
-     * @returns {TestRunnerAdapter}
-     */
     runnerFor(config: ProtractorConfig): TestRunnerAdapter {
 
         const
@@ -53,7 +45,7 @@ export class TestRunnerDetector {
                 return this.useCucumber(config);
             case !! config.mochaOpts:
                 return this.useMocha(config);
-            case !! config.jasmineNodeOpts:
+            case !! config.jasmineNodeOpts:     // eslint-disable-line unicorn/no-useless-switch-case
             default:
                 return this.useJasmine(config);
         }

package/src/adapter/runner/TestRunnerLoader.ts

@@ -1,15 +1,15 @@
 /* eslint-disable unicorn/prevent-abbreviations,@typescript-eslint/ban-types */
-import { Config, FileFinder, FileSystem, ModuleLoader, Path, TestRunnerAdapter } from '@serenity-js/core/lib/io';
-import { CucumberConfig } from '@serenity-js/cucumber/lib/cli';
+import { TestRunnerAdapter } from '@serenity-js/core/lib/adapter';
+import { Config, FileFinder, FileSystem, ModuleLoader, Path } from '@serenity-js/core/lib/io';
+import { CucumberConfig } from '@serenity-js/cucumber/lib/adapter';
 
 import { CucumberAdapterConfig } from './CucumberAdapterConfig';
 
 /**
- * @desc
- *  Loads a {@link @serenity-js/core/lib/io~TestRunnerAdapter}, needed to invoke
- *  the chosen test runner programmatically.
+ * Loads a {@apilink TestRunnerAdapter} needed to invoke
+ * the chosen test runner programmatically.
  *
- * @public
+ * @group Integration
  */
 export class TestRunnerLoader {
 
@@ -18,14 +18,14 @@ export class TestRunnerLoader {
     private readonly finder: FileFinder;
 
     /**
-     * @param {@serenity-js/core/lib/io~Path} cwd
+     * @param cwd
      *  Current working directory; used to resolve glob paths to files for Cucumber.js to `require`,
      *  and instructing Serenity/JS where to look for this module's optional
-     *  dependencies, like [`@serenity-js/cucumber`](/modules/cucumber),
-     *  [`@serenity-js/mocha`](/modules/mocha),
-     *  [`@serenity-js/jasmine`](/modules/jasmine), etc.
+     *  dependencies, like [`@serenity-js/cucumber`](/api/cucumber),
+     *  [`@serenity-js/mocha`](/api/mocha),
+     *  [`@serenity-js/jasmine`](/api/jasmine), etc.
      *
-     * @param {number | string} runnerId
+     * @param runnerId
      *  Unique identifier used to differentiate output files produced by native Cucumber.js formatters.
      *  For example, `process.pid`
      */
@@ -36,8 +36,9 @@ export class TestRunnerLoader {
     }
 
     /**
-     * @param {@serenity-js/jasmine/lib/adapter~JasmineConfig} jasmineNodeOpts
-     * @returns {@serenity-js/core/lib/io~TestRunnerAdapter}
+     * See {@apilink JasmineConfig}
+     *
+     * @param jasmineNodeOpts
      */
     forJasmine(jasmineNodeOpts: object /* JasmineConfig */): TestRunnerAdapter {
         const { JasmineAdapter } = this.moduleLoader.require('@serenity-js/jasmine/lib/adapter')
@@ -45,8 +46,9 @@ export class TestRunnerLoader {
     }
 
     /**
-     * @param {@serenity-js/mocha/lib/adapter~MochaConfig} mochaOpts
-     * @returns {@serenity-js/core/lib/io~TestRunnerAdapter}
+     * See {@apilink MochaConfig}
+     *
+     * @param mochaOpts
      */
     forMocha(mochaOpts: object /* MochaConfig */): TestRunnerAdapter {
         const { MochaAdapter } = this.moduleLoader.require('@serenity-js/mocha/lib/adapter')
@@ -54,13 +56,13 @@ export class TestRunnerLoader {
     }
 
     /**
+     * See {@apilink CucumberConfig}
      *
-     * @param {@serenity-js/cucumber/lib/cli~CucumberConfig} cucumberOpts
-     * @param {CucumberAdapterConfig} adapterConfig
-     * @returns {@serenity-js/core/lib/io~TestRunnerAdapter}
+     * @param cucumberOpts
+     * @param adapterConfig
      */
     forCucumber(cucumberOpts: object /* CucumberConfig */, adapterConfig: CucumberAdapterConfig): TestRunnerAdapter {
-        const { CucumberCLIAdapter, CucumberFormat, StandardOutput, TempFileOutput } = this.moduleLoader.require('@serenity-js/cucumber/lib/cli');
+        const { CucumberCLIAdapter, CucumberFormat, StandardOutput, TempFileOutput } = this.moduleLoader.require('@serenity-js/cucumber/lib/adapter');
 
         const config = new Config<CucumberConfig>(cucumberOpts)
             .where('require', requires =>