feat: set default browser orientation before each test

doc/config.md

@@ -248,6 +248,11 @@ Settings list:
 
   This is useful when the page has elements which are animated.
 
+* `orientation` – browser orientation that will be set before each test run. It is useful to restore the default browser orientation after test execution in which orientation was changed. There are 3 allowed values for this option:
+    * `null` (default). No action will be taken.
+    * `landscape`. Orientation will be changed to landscape mode before running the test.
+    * `portrait`. Orientation will be changed to portrait mode before running the test.
+
 ## Sets
 
 You can link some set of tests with certain browsers using `sets`.

lib/browser/browser.js

@@ -21,7 +21,15 @@ module.exports = class Browser {
     }
 
     serialize() {
-        const props = ['id', 'gridUrl', 'httpTimeout', 'screenshotMode', 'screenshotDelay', 'compositeImage'];
+        const props = [
+            'id',
+            'gridUrl',
+            'httpTimeout',
+            'screenshotMode',
+            'screenshotDelay',
+            'compositeImage',
+            'orientation'
+        ];
 
         return {
             config: _.pick(this.config, props),

lib/browser/new-browser.js

@@ -86,6 +86,7 @@ module.exports = class NewBrowser extends Browser {
     launch(calibrator) {
         return this.initSession()
             .then(() => this._setDefaultSize())
+            .then(() => this._setDefaultOrientation())
             .then(() => {
                 // maximize is required, because default
                 // windows size in phantomjs can prevent
@@ -182,6 +183,16 @@ module.exports = class NewBrowser extends Browser {
             });
     }
 
+    _setDefaultOrientation() {
+        const orientation = this.config.orientation;
+
+        if (!orientation) {
+            return;
+        }
+
+        return this._wd.setOrientation(orientation);
+    }
+
     openRelative(relativeURL) {
         return this.open(this.config.getAbsoluteUrl(relativeURL), {resetZoom: true});
     }

lib/config/browser-options.js

@@ -30,7 +30,8 @@ const getTopLevel = () => {
         retry: 0,
         screenshotMode: 'auto',
         compositeImage: false,
-        screenshotDelay: 0
+        screenshotDelay: 0,
+        orientation: null
     };
 
     const provideDefault = (key) => defaults[key];
@@ -217,7 +218,20 @@ function buildBrowserOptions(defaultFactory, extra) {
             }
         }),
 
-        compositeImage: booleanOption(defaultFactory('compositeImage'))
+        compositeImage: booleanOption(defaultFactory('compositeImage')),
+
+        orientation: option({
+            defaultValue: defaultFactory('orientation'),
+            validate: (value) => {
+                if (_.isNull(value)) {
+                    return;
+                }
+                is('string', 'orientation')(value);
+                if (value !== 'landscape' && value !== 'portrait') {
+                    throw new Error('"orientation" must be "landscape" or "portrait"');
+                }
+            }
+        })
     });
 }
 

test/unit/browser/new-browser.js

@@ -23,6 +23,7 @@ describe('browser/new-browser', () => {
             get: sinon.stub().returns(Promise.resolve({})),
             eval: sinon.stub().returns(Promise.resolve('')),
             setWindowSize: sinon.stub().returns(Promise.resolve({})),
+            setOrientation: sinon.stub().returns(Promise.resolve({})),
             maximize: sinon.stub().returns(Promise.resolve()),
             windowHandle: sinon.stub().returns(Promise.resolve({})),
             moveTo: sinon.stub().returns(Promise.resolve()),
@@ -257,6 +258,20 @@ describe('browser/new-browser', () => {
             return launchBrowser().then(() => assert.called(wd.maximize));
         });
 
+        describe('set default orientation', () => {
+            it('should set to value specified in config', () => {
+                browser.config.orientation = 'portrait';
+
+                return launchBrowser().then(() => assert.calledWith(wd.setOrientation, 'portrait'));
+            });
+
+            it('should do nothing if no value is specified', () => {
+                delete browser.config.orientation;
+
+                return launchBrowser().then(() => assert.notCalled(wd.setOrientation));
+            });
+        });
+
         describe('with windowSize option', () => {
             beforeEach(() => browser.config.windowSize = {width: 1024, height: 768});
 

test/unit/config-options/config-options.test.js

@@ -911,6 +911,68 @@ describe('config', function() {
             });
         });
 
+        describe('orientation', function() {
+            it('should be null by default', function() {
+                var config = createBrowserConfig();
+
+                assert.isNull(config.orientation);
+            });
+
+            it('should accept "portrait" value', function() {
+                var config = createBrowserConfig({
+                    orientation: 'portrait'
+                });
+
+                assert.equal(config.orientation, 'portrait');
+            });
+
+            it('should accept "landscape" value', function() {
+                var config = createBrowserConfig({
+                    orientation: 'landscape'
+                });
+
+                assert.equal(config.orientation, 'landscape');
+            });
+
+            it('should not accept any other string value', function() {
+                assert.throws(function() {
+                    createBrowserConfig({
+                        orientation: 'lalalal'
+                    });
+                }, /"orientation" must be "landscape" or "portrait"/);
+            });
+
+            it('should not accept non-string value', function() {
+                assert.throws(function() {
+                    createBrowserConfig({
+                        orientation: 100
+                    });
+                }, /a value must be string/);
+            });
+
+            shouldBeSettableFromTopLevel('orientation', 'portrait');
+            shouldOverrideTopLevelValue('orientation', {
+                top: 'portrait',
+                browser: 'landscape'
+            });
+
+            it('should correctly parse env var', function() {
+                assertParsesEnv({
+                    property: 'browsers.browser.orientation',
+                    value: 'portrait',
+                    expected: 'portrait'
+                });
+            });
+
+            it('should correctly parse cli flag', function() {
+                assertParsesCli({
+                    property: 'browsers.browser.orientation',
+                    value: 'portrait',
+                    expected: 'portrait'
+                });
+            });
+        });
+
         describe('desiredCapabilities', function() {
             it('should accept objects', function() {
                 var config = createBrowserConfig({