Implement Browserstack Automate support. Add status reporting (closes #22) (#23)

* Implement Browserstack Automate support (closes #22)

* Fix README

Author: AndreyBelym

Gulpfile.js

@@ -1,7 +1,6 @@
 var path        = require('path');
 var gulp        = require('gulp');
 var babel       = require('gulp-babel');
-var mocha       = require('gulp-mocha');
 var sequence    = require('gulp-sequence');
 var del         = require('del');
 var nodeVersion = require('node-version');
@@ -42,43 +41,68 @@ gulp.task('build', ['lint', 'clean'], function () {
         .pipe(gulp.dest('lib'));
 });
 
-gulp.task('test-mocha', ['build'], function () {
+function testMocha () {
     if (!process.env.BROWSERSTACK_USERNAME || !process.env.BROWSERSTACK_ACCESS_KEY)
         throw new Error('Specify your credentials by using the BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY environment variables to authenticate to BrowserStack.');
 
+
+    var mochaCmd = path.join(__dirname, 'node_modules/.bin/mocha');
+
+    var mochaOpts = [
+        '--ui', 'bdd',
+        '--reporter', 'spec',
+        '--timeout', typeof v8debug === 'undefined' ? 2000 : Infinity,
+        'test/mocha/**/*test.js'
+    ];
+
+    // NOTE: we must add the parent of plugin directory to NODE_PATH, otherwise testcafe will not be able
+    // to find the plugin. So this function starts mocha with proper NODE_PATH.
     process.env.NODE_PATH = PACKAGE_SEARCH_PATH;
 
-    return gulp
-        .src('test/mocha/**.js')
-        .pipe(mocha({
-            ui:       'bdd',
-            reporter: 'spec',
-            timeout:  typeof v8debug === 'undefined' ? 2000 : Infinity // NOTE: disable timeouts in debug
-        }));
+    return execa(mochaCmd, mochaOpts, { stdio: 'inherit' });
+}
+
+gulp.task('test-mocha', ['build'], function () {
+    process.env.BROWSERSTACK_USE_AUTOMATE = 0;
+
+    return testMocha();
 });
 
-gulp.task('test-testcafe', ['build'], function () {
+gulp.task('test-mocha-automate', ['build'], function () {
+    process.env.BROWSERSTACK_USE_AUTOMATE = 1;
+
+    return testMocha();
+});
+
+function testTestcafe () {
     if (!process.env.BROWSERSTACK_USERNAME || !process.env.BROWSERSTACK_ACCESS_KEY)
         throw new Error('Specify your credentials by using the BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY environment variables to authenticate to BrowserStack.');
 
     var testCafeCmd = path.join(__dirname, 'node_modules/.bin/testcafe');
 
     var testCafeOpts = [
-        'browserstack:chrome,browserstack:Google Pixel,browserstack:iPhone SE',
-        'test/testcafe/**/*.js',
+        'browserstack:chrome:windows 10,browserstack:Google Pixel@7.1,browserstack:iPhone 8',
+        'test/testcafe/**/*test.js',
         '-s', '.screenshots'
     ];
 
     // NOTE: we must add the parent of plugin directory to NODE_PATH, otherwise testcafe will not be able
     // to find the plugin. So this function starts testcafe with proper NODE_PATH.
     process.env.NODE_PATH = PACKAGE_SEARCH_PATH;
 
-    var child = execa(testCafeCmd, testCafeOpts);
+    return execa(testCafeCmd, testCafeOpts, { stdio: 'inherit' });
+}
+
+gulp.task('test-testcafe', ['build'], function () {
+    process.env.BROWSERSTACK_USE_AUTOMATE = '0';
+
+    return testTestcafe();
+});
 
-    child.stdout.pipe(process.stdout);
-    child.stderr.pipe(process.stderr);
+gulp.task('test-testcafe-automate', ['build'], function () {
+    process.env.BROWSERSTACK_USE_AUTOMATE = '1';
 
-    return child;
+    return testTestcafe();
 });
 
-gulp.task('test', sequence('test-mocha', 'test-testcafe'));
+gulp.task('test', sequence('test-mocha', 'test-mocha-automate', 'test-testcafe', 'test-testcafe-automate'));

README.md

@@ -49,5 +49,18 @@ Proxy options can be passed via envrionment variables.
  - `BROWSERSTACK_FORCE_PROXY` - if it's not empty, forces all traffic of Browserstack local binary to go through the proxy,
  - `BROWSERSTACK_FORCE_LOCAL` - if it's not empty, forces all traffic of Browserstack local binary to go through the local machine
 
+## Browserstack JS Testing and Browserstack Automate 
+Browserstack offers two APIs for browser testing:
+ - [Browserstack JS Testing](https://www.browserstack.com/javascript-testing-api)
+ - [Browserstack Automate](https://www.browserstack.com/automate)
+ 
+ JS testing supports more types of devices (compare: [JS Testing devices](https://www.browserstack.com/list-of-browsers-and-platforms?product=js_testing) 
+ vs [Automate devices](https://www.browserstack.com/list-of-browsers-and-platforms?product=automate)), 
+ while Automate allows for much longer tests ([2 hours](https://www.browserstack.com/automate/timeouts) vs [30 minutes](https://github.com/browserstack/api#timeout300)) 
+ and provides some additional features (like the window resizing functionality).
+    
+ TestCafe uses the JS Testing API by default. In order to use Browserstack Automate, 
+ set the `BROWSERSTACK_USE_AUTOMATE` environment variable to `1`.
+
 ## Author
 Developer Express Inc. (https://devexpress.com)

package.json

@@ -47,15 +47,15 @@
     "babel-preset-stage-3": "^6.11.0",
     "chai": "^3.5.0",
     "del": "^2.2.2",
-    "execa": "^0.4.0",
+    "execa": "^0.9.0",
     "gulp": "^3.9.0",
     "gulp-babel": "^6.1.2",
     "gulp-eslint": "^3.0.1",
-    "gulp-mocha": "^3.0.1",
     "gulp-sequence": "^0.4.6",
+    "mocha": "^5.0.1",
     "node-version": "^1.0.0",
     "publish-please": "^2.1.4",
-    "testcafe": "^0.13.0",
+    "testcafe": "latest",
     "tmp": "0.0.31"
   }
 }

src/backends/automate.js

@@ -0,0 +1,177 @@
+import Promise from 'pinkie';
+import jimp from 'jimp';
+import BaseBackend from './base';
+import requestApiBase from '../utils/request-api';
+import createBrowserstackStatus from '../utils/create-browserstack-status';
+
+
+const API_POLLING_INTERVAL = 80000;
+
+const BROWSERSTACK_API_PATHS = {
+    browserList: {
+        url: 'https://api.browserstack.com/automate/browsers.json'
+    },
+
+    newSession: {
+        url:    'http://hub-cloud.browserstack.com/wd/hub/session',
+        method: 'POST'
+    },
+
+    openUrl: id => ({
+        url:    `http://hub-cloud.browserstack.com/wd/hub/session/${id}/url`,
+        method: 'POST'
+    }),
+
+    getWindowSize: id => ({
+        url: `http://hub-cloud.browserstack.com/wd/hub/session/${id}/window/current/size`
+    }),
+
+    setWindowSize: id => ({
+        url:    `http://hub-cloud.browserstack.com/wd/hub/session/${id}/window/current/size`,
+        method: 'POST'
+    }),
+
+    maximizeWindow: id => ({
+        url:    `http://hub-cloud.browserstack.com/wd/hub/session/${id}/window/current/maximize`,
+        method: 'POST'
+    }),
+
+    getUrl: id => ({
+        url: `http://hub-cloud.browserstack.com/wd/hub/session/${id}/url`
+    }),
+
+    deleteSession: id => ({
+        url:    `http://hub-cloud.browserstack.com/wd/hub/session/${id}`,
+        method: 'DELETE'
+    }),
+
+    screenshot: id => ({
+        url: `http://hub-cloud.browserstack.com/wd/hub/session/${id}/screenshot`
+    }),
+
+    getStatus: id => ({
+        url: `https://api.browserstack.com/automate/sessions/${id}.json`
+    }),
+
+    setStatus: id => ({
+        url:    `https://api.browserstack.com/automate/sessions/${id}.json`,
+        method: 'PUT'
+    })
+};
+
+
+function requestApi (path, params) {
+    return requestApiBase(path, params)
+        .then(response => {
+            if (response.status !== 0)
+                throw new Error(`API error ${response.status}: ${response.value.message}`);
+
+            return response;
+        });
+}
+
+function getCorrectedSize (currentClientAreaSize, currentWindowSize, requestedSize) {
+    var horizontalChrome = currentWindowSize.width - currentClientAreaSize.width;
+    var verticalChrome   = currentWindowSize.height - currentClientAreaSize.height;
+
+    return {
+        width:  requestedSize.width + horizontalChrome,
+        height: requestedSize.height + verticalChrome
+    };
+}
+
+export default class AutomateBackend extends BaseBackend {
+    constructor (...args) {
+        super(...args);
+
+        this.sessions = {};
+    }
+
+    async _requestSessionUrl (id) {
+        var sessionInfo = await requestApiBase(BROWSERSTACK_API_PATHS.getStatus(this.sessions[id].sessionId));
+
+        return sessionInfo['automation_session']['browser_url'];
+    }
+
+    async _requestCurrentWindowSize (id) {
+        var currentWindowSizeData = await requestApi(BROWSERSTACK_API_PATHS.getWindowSize(this.sessions[id].sessionId));
+
+        return {
+            width:  currentWindowSizeData.value.width,
+            height: currentWindowSizeData.value.height
+        };
+    }
+
+    async getBrowsersList () {
+        var platformsInfo = await requestApiBase(BROWSERSTACK_API_PATHS.browserList);
+
+        return platformsInfo.reverse();
+    }
+
+    getSessionUrl (id) {
+        return this.sessions[id] ? this.sessions[id].sessionUrl : '';
+    }
+
+    async openBrowser (id, pageUrl, capabilities) {
+        var { localIdentifier, local, ...restCapabilities } = capabilities;
+
+        capabilities = {
+            'browserstack.localIdentifier': localIdentifier,
+            'browserstack.local':           local,
+            ...restCapabilities
+        };
+
+        this.sessions[id] = await requestApi(BROWSERSTACK_API_PATHS.newSession, {
+            body: { desiredCapabilities: capabilities },
+
+            executeImmediately: true
+        });
+
+        this.sessions[id].sessionUrl = await this._requestSessionUrl(id);
+
+        var sessionId = this.sessions[id].sessionId;
+
+        this.sessions[id].interval = setInterval(() => requestApi(BROWSERSTACK_API_PATHS.getUrl(sessionId), { executeImmediately: true }), API_POLLING_INTERVAL);
+
+        await requestApi(BROWSERSTACK_API_PATHS.openUrl(sessionId), { body: { url: pageUrl } });
+    }
+
+    async closeBrowser (id) {
+        clearInterval(this.sessions[id].interval);
+
+        await requestApi(BROWSERSTACK_API_PATHS.deleteSession(this.sessions[id].sessionId));
+    }
+
+    async takeScreenshot (id, screenshotPath) {
+        return new Promise(async (resolve, reject) => {
+            var base64Data = await requestApi(BROWSERSTACK_API_PATHS.screenshot(this.sessions[id].sessionId));
+            var buffer     = Buffer.from(base64Data.value, 'base64');
+
+            jimp
+                .read(buffer)
+                .then(image => image.write(screenshotPath, resolve))
+                .catch(reject);
+        });
+    }
+
+    async resizeWindow (id, width, height, currentWidth, currentHeight) {
+        var sessionId             = this.sessions[id].sessionId;
+        var currentWindowSize     = await this._requestCurrentWindowSize(id);
+        var currentClientAreaSize = { width: currentWidth, height: currentHeight };
+        var requestedSize         = { width, height };
+        var correctedSize         = getCorrectedSize(currentClientAreaSize, currentWindowSize, requestedSize);
+
+        await requestApi(BROWSERSTACK_API_PATHS.setWindowSize(sessionId), { body: correctedSize });
+    }
+
+    async maximizeWindow (id) {
+        await requestApi(BROWSERSTACK_API_PATHS.maximizeWindow(this.sessions[id].sessionId));
+    }
+
+    async reportJobResult (id, jobResult, jobData, possibleResults) {
+        var sessionId = this.sessions[id].sessionId;
+        var jobStatus = createBrowserstackStatus(jobResult, jobData, possibleResults);
+
+        await requestApiBase(BROWSERSTACK_API_PATHS.setStatus(sessionId), { body: jobStatus });
+    }
+}

src/backends/base.js

@@ -0,0 +1,37 @@
+export default class BaseBackend {
+    constructor (reportWarning) {
+        this.reportWarning = reportWarning;
+    }
+
+    async getBrowsersList () {
+        throw new Error('Not implemented');
+    }
+
+    async openBrowser (/*id, pageUrl, capabilities*/) {
+        throw new Error('Not implemented');
+    }
+
+    async closeBrowser (/*id*/) {
+        throw new Error('Not implemented');
+    }
+
+    async takeScreenshot (/*id, path*/) {
+        throw new Error('Not implemented');
+    }
+
+    async resizeWindow (/*id, width, height, currentWidth, currentHeight*/) {
+        throw new Error('Not implemented');
+    }
+
+    async maximizeWindow (/*id*/) {
+        throw new Error('Not implemented');
+    }
+
+    async reportJobResult (/*id, jobStatus, jobData, possibleStatuses*/) {
+        throw new Error('Not implemented');
+    }
+
+    getSessionUrl (/*id*/) {
+        throw new Error('Not implemented');
+    }
+}