Skip to content
Permalink
Browse files
fix(protractor): documentation and examples for all the interactions
  • Loading branch information
jan-molak committed Oct 5, 2020
1 parent ea77fca commit 39a175d7139d6733748dcce317196794042b6a36
Show file tree
Hide file tree
Showing 48 changed files with 1,648 additions and 434 deletions.
@@ -1,9 +1,9 @@
/**
* @external {ElementFinder} https://www.protractortest.org/#/api?view=ElementFinder
* @external {ElementArrayFinder} https://www.protractortest.org/#/api?view=ElementArrayFinder
*/

/**
* @external {ElementArrayFinder} https://www.protractortest.org/#/api?view=ElementArrayFinder
* @external {ElementFinder} https://www.protractortest.org/#/api?view=ElementFinder
*/

/**
@@ -6,20 +6,24 @@
* @external {selenium-webdriver~AlertPromise} https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/webdriver_exports_AlertPromise.html
*/

/**
* @external {selenium-webdriver~By} https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/by_exports_By.html
*/

/**
* @external {selenium-webdriver~Capabilities} https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_Capabilities.html
*/

/**
* @external {selenium-webdriver~Navigation} https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/webdriver_exports_Navigation.html
* @external {selenium-webdriver~Key} https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_Key.html
*/

/**
* @external {selenium-webdriver~Options} https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/ie_exports_Options.html
* @external {selenium-webdriver~Navigation} https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/webdriver_exports_Navigation.html
*/

/**
* @external {selenium-webdriver~By} https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/by_exports_By.html
* @external {selenium-webdriver~Options} https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/ie_exports_Options.html
*/

/**
@@ -76,7 +76,9 @@ class Plugin {
const
module = moduleNameFrom(doc.importPath),
id = `${doc.importPath}~${doc.name}`,
pathToDocs = `/modules/${ module }/${ doc.kind }/${ doc.longname }.html`;
pathToDocs = doc.kind !== 'function'
? `/modules/${ module }/${ doc.kind }/${ doc.longname }.html`
: `/modules/${ module }/${ doc.kind }/index.html#static-function-${ doc.name }`;

exported[module] = exported[module] || [];
exported[module].push({
@@ -8,13 +8,13 @@ import { by } from 'protractor';
import { Attribute, Click, Navigate, Target } from '../../../src';
import { pageFromTemplate } from '../../fixtures';

/** @test {Click} */
describe('Click', () => {

const Form = {
Checkbox: Target.the('checkbox').located(by.id('no-spam-please')),
};

/** @test {Click} */
/** @test {Click.on} */
it('allows the actor to click on an element', () => actorCalled('Bernie').attemptsTo(
Navigate.to(pageFromTemplate(`
@@ -8,6 +8,7 @@ import { by } from 'protractor';
import { Attribute, Hover, Navigate, Target } from '../../../src';
import { pageFromTemplate } from '../../fixtures';

/** @test {Hover} */
describe('Hover', function () {

const pageWithALink = pageFromTemplate(`
@@ -16,8 +17,7 @@ describe('Hover', function () {
<h1>A page with a link</h1>
<a href="javascript:void(0)"
class="off"
onmouseover="this.className='on';" onmouseout="this.className='off';">
>link</a>
onmouseover="this.className='on';" onmouseout="this.className='off';">link</a>
</body>
</html>
`);
@@ -27,9 +27,8 @@ describe('Hover', function () {
Link: Target.the('link').located(by.css('a')),
};

/** @test {Scroll} */
/** @test {Scroll.to} */
it('allows the actor to move the mouse to a given target', () => actorCalled('Mickey').attemptsTo(
/** @test {Hover.over} */
it('allows the actor to position the mouse cursor over a given target', () => actorCalled('Mickey').attemptsTo(
Navigate.to(pageWithALink),

Ensure.that(Attribute.of(Page.Link).called('class'), equals('off')),
@@ -41,7 +40,7 @@ describe('Hover', function () {
Ensure.that(Attribute.of(Page.Link).called('class'), equals('off')),
));

/** @test {Enter#toString} */
/** @test {Hover#toString} */
it('provides a sensible description of the interaction being performed', () => {
expect(Hover.over(Page.Link).toString())
.to.equal(`#actor hovers the mouse over the link`);
@@ -8,6 +8,7 @@ import { by } from 'protractor';
import { Navigate, Target, Text, Website } from '../../../src';
import { pageFromTemplate } from '../../fixtures';

/** @test {Navigate} */
describe('Navigate', () => {

describe('to(url)', () => {
@@ -25,6 +26,7 @@ describe('Navigate', () => {
Ensure.that(Text.of(Target.the('heading').located(by.id('h'))), equals('Hello World')),
));

/** @test {Navigate.to} */
/** @test {Navigate#toString} */
it('provides a sensible description of the interaction being performed', () => {
expect(Navigate.to(`https://serenity-js.org`).toString())
@@ -34,6 +36,7 @@ describe('Navigate', () => {

describe('to(url).withTimeout(duration)', function () {

/** @test {Navigate.to} */
/** @test {Navigate#toString} */
it('provides a sensible description of the interaction being performed', () => {
expect(Navigate.to(`https://serenity-js.org`).withTimeout(Duration.ofSeconds(5)).toString())
@@ -53,6 +56,7 @@ describe('Navigate', () => {
Ensure.that(Website.url(), endsWith('version/')),
));

/** @test {Navigate.back} */
/** @test {Navigate#toString} */
it('provides a sensible description of the interaction being performed', () => {
expect(Navigate.back().toString())
@@ -73,6 +77,7 @@ describe('Navigate', () => {
Ensure.that(Website.url(), endsWith('accessibility/')),
));

/** @test {Navigate.forward} */
/** @test {Navigate#toString} */
it('provides a sensible description of the interaction being performed', () => {
expect(Navigate.forward().toString())
@@ -81,7 +86,8 @@ describe('Navigate', () => {
});

describe('reloadPage', () => {
/** @test {Navigate.to} */

/** @test {Navigate.reloadPage} */
it('allows the actor to navigate to a desired destination', () => actorCalled('Bernie').attemptsTo(
Navigate.to(pageFromTemplate(`
<html>
@@ -101,6 +107,7 @@ describe('Navigate', () => {
Ensure.that(Text.of(Target.the('heading').located(by.id('h'))), equals('Reloaded')),
));

/** @test {Navigate.reloadPage} */
/** @test {Navigate#toString} */
it('provides a sensible description of the interaction being performed', () => {
expect(Navigate.reloadPage().toString())
@@ -2,13 +2,14 @@ import 'mocha';

import { expect } from '@integration/testing-tools';
import { Ensure, equals } from '@serenity-js/assertions';
import { actorCalled } from '@serenity-js/core';
import { actorCalled, Question } from '@serenity-js/core';
import { given } from 'mocha-testdata';
import { by, Key } from 'protractor';

import { Navigate, Press, Target, Value } from '../../../src';
import { pageFromTemplate } from '../../fixtures';

/** @test {Press} */
describe('Press', () => {

const Form = {
@@ -27,7 +28,6 @@ describe('Press', () => {

describe('single keys', () => {

/** @test {Press} */
/** @test {Press.the} */
it('allows the actor to enter keys individually into a field', () => actorCalled('Bernie').attemptsTo(
Navigate.to(page),
@@ -42,7 +42,6 @@ describe('Press', () => {

describe('keyboard shortcuts', function () {

/** @test {Press} */
/** @test {Press.the} */
it('allows the actor to use keyboard shortcuts', () => actorCalled('Bernie').attemptsTo(
Navigate.to(page),
@@ -51,7 +50,6 @@ describe('Press', () => {

Ensure.that(Value.of(Form.Text_Field), equals(`A`)),
));

});

given([
@@ -1,26 +1,47 @@
import 'mocha';
import { expect } from '@integration/testing-tools';

import { Ensure, equals } from '@serenity-js/assertions';
import { actorCalled, Note, TakeNote } from '@serenity-js/core';
import { ResizeBrowserWindow, Window } from '../../../src';

/** @test {ResizeBrowserWindow} */
describe('ResizeBrowserWindow', () => {

/** @test {ResizeBrowserWindow} */
/** @test {ResizeBrowserWindow.to} */
it('allows the actor to change width and height of browser window', () => actorCalled('Nick').attemptsTo(
ResizeBrowserWindow.to(640, 480),
Ensure.that(Window.size(), equals({width: 640, height: 480})),
ResizeBrowserWindow.to(480, 640),
Ensure.that(Window.size(), equals({width: 480, height: 640})),
));

/** @test {ResizeBrowserWindow.toMaximum} */
it('allows the actor to resize browser window to maximum', () => actorCalled('Nick').attemptsTo(
ResizeBrowserWindow.toMaximum(),
TakeNote.of(Window.size()),
ResizeBrowserWindow.to(480, 640),
ResizeBrowserWindow.toMaximum(),
Ensure.that(Note.of(Window.size()), equals(Window.size())),
));
describe(`to()`, () => {

/** @test {ResizeBrowserWindow.to} */
it('allows the actor to change width and height of the browser window', () =>
actorCalled('Nick').attemptsTo(
ResizeBrowserWindow.to(640, 480),
Ensure.that(Window.size(), equals({width: 640, height: 480})),
ResizeBrowserWindow.to(480, 640),
Ensure.that(Window.size(), equals({width: 480, height: 640})),
));

/** @test {ResizeBrowserWindow.to} */
/** @test {ResizeBrowserWindow#toString} */
it('produces a sensible description of the interaction being performed', () => {
expect(ResizeBrowserWindow.to(640, 480).toString()).equals('#actor sets the size of the browser window to 640 x 480');
});
});

describe('toMaximum()', () => {

/** @test {ResizeBrowserWindow.toMaximum} */
it('allows the actor to resize browser window to maximum', () =>
actorCalled('Nick').attemptsTo(
ResizeBrowserWindow.toMaximum(),
TakeNote.of(Window.size()),
ResizeBrowserWindow.to(480, 640),
ResizeBrowserWindow.toMaximum(),
Ensure.that(Note.of(Window.size()), equals(Window.size())),
));

/** @test {ResizeBrowserWindow.toMaximum} */
/** @test {ResizeBrowserWindow#toString} */
it('produces a sensible description of the interaction being performed', () => {
expect(ResizeBrowserWindow.toMaximum().toString()).equals('#actor maximises the browser window');
});
});
});
@@ -8,6 +8,7 @@ import { by } from 'protractor';
import { ExecuteScript, LastScriptExecution, Navigate, Scroll, Target } from '../../../src';
import { pageFromTemplate } from '../../fixtures';

/** @test {Scroll} */
describe('Scroll', function () {

const aLongSpell = pageFromTemplate(`
@@ -22,7 +23,6 @@ describe('Scroll', function () {
Execute_Button: Target.the('"Cast!" button').located(by.id('cast')),
};

/** @test {Scroll} */
/** @test {Scroll.to} */
it('allows the actor to scroll to a given target so that it appears in the viewport', () => actorCalled('Gandalf').attemptsTo(
Navigate.to(aLongSpell),
@@ -36,7 +36,8 @@ describe('Scroll', function () {
Ensure.that(LastScriptExecution.result<number>(), isLessThan(1000)),
));

/** @test {Enter#toString} */
/** @test {Scroll.to} */
/** @test {Scroll#toString} */
it('provides a sensible description of the interaction being performed', () => {
expect(Scroll.to(Page.Execute_Button).toString())
.to.equal(`#actor scrolls to the "Cast!" button`);
@@ -8,6 +8,7 @@ import { Navigate, Select, Selected, Target, Text } from '../../../src';
import { pageFromTemplate } from '../../fixtures';
import { UIActors } from '../../UIActors';

/** @test {Select} */
describe('Select', () => {

const pageWithSingleSelect = pageFromTemplate(`
@@ -216,42 +217,49 @@ describe('Select', () => {
describe('toString()', () => {

/** @test {Select.value} */
/** @test {Select#toString} */
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`);
});

/** @test {Selected.valueOf} */
/** @test {Select#toString} */
it('provides a sensible description of Selected.valueOf', () => {
expect(Selected.valueOf(SingleSelectPage.selector).toString())
.to.equal(`value selected in the country selector`);
});

/** @test {Select.option} */
/** @test {Select#toString} */
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`);
});

/** @test {Selected.optionIn} */
/** @test {Select#toString} */
it('provides a sensible description of Selected.optionIn()', () => {
expect(Selected.optionIn(SingleSelectPage.selector).toString())
.to.equal(`option selected in the country selector`);
});

/** @test {Select.values} */
/** @test {Select#toString} */
it('provides a sensible description of Select.values()', () => {
expect(Select.values(['PL', 'DE'], 'FR').from(MultiSelectPage.selector).toString())
.to.equal(`#actor selects values 'PL', 'DE' and 'FR' from the country selector`);
});

/** @test {Selected.valuesOf} */
/** @test {Select#toString} */
it('provides a sensible description of Select.valuesOf()', () => {
expect(Selected.valuesOf(MultiSelectPage.selector).toString())
.to.equal(`values selected in the country selector`);
});

/** @test {Select.options} */
/** @test {Select#toString} */
it('provides a sensible description of Select.options()', () => {
expect(
Select.options(
@@ -263,6 +271,7 @@ describe('Select', () => {
});

/** @test {Selected.optionsIn} */
/** @test {Select#toString} */
it('provides a sensible description of Selected.optionsIn()', () => {
expect(Selected.optionsIn(MultiSelectPage.selector).toString())
.to.equal(`options selected in the country selector`);
@@ -8,6 +8,7 @@ import { Navigate, TakeScreenshot } from '../../../src';
import { pageFromTemplate } from '../../fixtures';
import { UIActors } from '../../UIActors';

/** @test {TakeScreenshot} */
describe('TakeScreenshot', () => {

let recorder: EventRecorder;
@@ -31,7 +32,6 @@ describe('TakeScreenshot', () => {
</html>
`);

/** @test {TakeScreenshot} */
/** @test {TakeScreenshot.of} */
it('allows the actor to take a screenshot with an arbitrary name', () => actorCalled('Bernie').attemptsTo(
Navigate.to(page),
@@ -43,6 +43,7 @@ describe('TakeScreenshot', () => {
});
}));

/** @test {TakeScreenshot.of} */
/** @test {TakeScreenshot#toString} */
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'`);

0 comments on commit 39a175d

Please sign in to comment.