feat(interactions): useAngular.disableSynchronisation() and UseAngula…

…r.enableSynchronisation() inter

affects: serenity-js

It's now easier to toggle Angular synchronisation during the actor flow, which enables switching
between angular and non-angular apps as part of the same scenario.

packages/serenity-js/spec/cookbook/content.recipe.ts

@@ -2,7 +2,7 @@ import expect = require('../expect');
 
 import { by, protractor } from 'protractor';
 
-import { Actor, Attribute, BrowseTheWeb, Target, Website } from '../../src/screenplay-protractor';
+import { Actor, Attribute, BrowseTheWeb, Target, UseAngular, Website } from '../../src/screenplay-protractor';
 import { Open, Text, WebElement } from '../../src/serenity-protractor';
 
 import { AppServer } from '../support/server';
@@ -26,11 +26,10 @@ describe ('When demonstrating the usage of a HTML page, a test scenario', functi
     const james = Actor.named('James').whoCan(BrowseTheWeb.using(protractor.browser));
 
     before(app.start());
-    before(() => {
-        // this is a standard, non-angular website; no need for angular-specific synchronisation here
-        protractor.browser.ignoreSynchronization = true;
-    });
-    before(() => james.attemptsTo(Open.browserOn(app.demonstrating('content'))));
+    before(() => james.attemptsTo(
+        UseAngular.disableSynchronisation(),            // this is a standard, non-angular website;
+        Open.browserOn(app.demonstrating('content')),   // no need for angular-specific synchronisation here
+    ));
     after(app.stop());
 
     it ('can read the text of on-screen elements', () => Promise.all([

packages/serenity-js/src/serenity-protractor/screenplay/abilities/browse_the_web.ts

@@ -72,6 +72,10 @@ export class BrowseTheWeb implements Ability {
         );
     }
 
+    enableAngularSynchronisation(enable: boolean): PromiseLike<any> {
+        return this.browser.waitForAngularEnabled(enable);
+    }
+
     executeScript(script: string, target: Target): PromiseLike<any> {
         return this.browser.executeScript(script, target.resolveUsing(this.browser.element));
     }

packages/serenity-js/src/serenity-protractor/screenplay/interactions/index.ts

@@ -8,4 +8,5 @@ export * from './hit';
 export * from './open';
 export * from './resize_browser_window';
 export * from './select';
+export * from './use_angular';
 export * from './wait';

packages/serenity-js/src/serenity-protractor/screenplay/interactions/use_angular.ts

@@ -0,0 +1,16 @@
+import { Interaction, UsesAbilities } from '../../../serenity/screenplay';
+import { BrowseTheWeb } from '../abilities/browse_the_web';
+
+export class UseAngular {
+    static disableSynchronisation = (): Interaction => new EnableAngularSynchronisation(false);
+    static enableSynchronisation  = (): Interaction => new EnableAngularSynchronisation(true);
+}
+
+class EnableAngularSynchronisation implements Interaction {
+    performAs(actor: UsesAbilities): PromiseLike<any> {
+        return BrowseTheWeb.as(actor).enableAngularSynchronisation(this.enable);
+    }
+
+    constructor(private enable: boolean) {
+    }
+}