cypress 3.1.4 → 3.3.1

package/lib/cli.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var _templateObject = _taggedTemplateLiteral(['\n    runs Cypress in the browser with the given name.\n    note: using an external browser will not record a video.\n  '], ['\n    runs Cypress in the browser with the given name.\n    note: using an external browser will not record a video.\n  ']);
+var _templateObject = _taggedTemplateLiteral(['\n    ', ' Warning: It looks like you\'re passing --spec a space-separated list of files:\n\n    "', '"\n\n    This will work, but it\'s not recommended.\n\n    The most common cause of this warning is using an unescaped glob pattern. If you are\n    trying to pass a glob pattern, escape it using quotes:\n      cypress run --spec "**/*.spec.js"\n\n    If you are trying to pass multiple spec filenames, separate them by commas instead:\n      cypress run --spec spec1,spec2,spec3\n  '], ['\n    ', ' Warning: It looks like you\'re passing --spec a space-separated list of files:\n\n    "', '"\n\n    This will work, but it\'s not recommended.\n\n    The most common cause of this warning is using an unescaped glob pattern. If you are\n    trying to pass a glob pattern, escape it using quotes:\n      cypress run --spec "**/*.spec.js"\n\n    If you are trying to pass multiple spec filenames, separate them by commas instead:\n      cypress run --spec spec1,spec2,spec3\n  ']);
 
 function _taggedTemplateLiteral(strings, raw) { return Object.freeze(Object.defineProperties(strings, { raw: { value: Object.freeze(raw) } })); }
 
@@ -8,8 +8,9 @@ var _ = require('lodash');
 var commander = require('commander');
 
 var _require = require('common-tags'),
-    oneLine = _require.oneLine;
+    stripIndent = _require.stripIndent;
 
+var logSymbols = require('log-symbols');
 var debug = require('debug')('cypress:cli');
 var util = require('./util');
 var logger = require('./logger');
@@ -26,8 +27,7 @@ function unknownOption(flag) {
   logger.error('  error: unknown ' + type + ':', flag);
   logger.error();
   this.outputHelp();
-  logger.error();
-  process.exit(1);
+  util.exit(1);
 }
 commander.Command.prototype.unknownOption = unknownOption;
 
@@ -35,6 +35,37 @@ var coerceFalse = function coerceFalse(arg) {
   return arg !== 'false';
 };
 
+var spaceDelimitedSpecsMsg = function spaceDelimitedSpecsMsg(files) {
+  logger.log();
+  logger.warn(stripIndent(_templateObject, logSymbols.warning, files.join(' ')));
+  logger.log();
+};
+
+var parseVariableOpts = function parseVariableOpts(fnArgs, args) {
+  var opts = fnArgs.pop();
+
+  if (fnArgs.length && opts.spec) {
+    // this will capture space-delimited specs after --spec spec1 but before the next option
+
+    var argIndex = _.indexOf(args, '--spec') + 2;
+    var nextOptOffset = _.findIndex(_.slice(args, argIndex), function (arg) {
+      return _.startsWith(arg, '--');
+    });
+    var endIndex = nextOptOffset !== -1 ? argIndex + nextOptOffset : args.length;
+
+    var maybeSpecs = _.slice(args, argIndex, endIndex);
+    var extraSpecs = _.intersection(maybeSpecs, fnArgs);
+
+    if (extraSpecs.length) {
+      opts.spec = [opts.spec].concat(extraSpecs);
+      spaceDelimitedSpecsMsg(opts.spec);
+      opts.spec = opts.spec.join(',');
+    }
+  }
+
+  return parseOpts(opts);
+};
+
 var parseOpts = function parseOpts(opts) {
   opts = _.pick(opts, 'project', 'spec', 'reporter', 'reporterOptions', 'path', 'destination', 'port', 'env', 'cypressVersion', 'config', 'record', 'key', 'browser', 'detached', 'headed', 'global', 'dev', 'force', 'exit', 'cachePath', 'cacheList', 'cacheClear', 'parallel', 'group', 'ciBuildId');
 
@@ -56,7 +87,8 @@ var descriptions = {
   port: 'runs Cypress on a specific port. overrides any value in cypress.json.',
   env: 'sets environment variables. separate multiple values with a comma. overrides any value in cypress.json or cypress.env.json',
   config: 'sets configuration values. separate multiple values with a comma. overrides any value in cypress.json.',
-  browser: oneLine(_templateObject),
+  browserRunMode: 'runs Cypress in the browser with the given name. if a filesystem path is supplied, Cypress will attempt to use the browser at that path.',
+  browserOpenMode: 'path to a custom browser to be added to the list of available browsers in Cypress',
   detached: 'runs Cypress application in detached mode',
   project: 'path to the project',
   global: 'force Cypress into global mode as if its globally installed',
@@ -65,9 +97,9 @@ var descriptions = {
   dev: 'runs cypress in development and bypasses binary check',
   forceInstall: 'force install the Cypress binary',
   exit: 'keep the browser open after tests finish',
-  cachePath: 'print the cypress binary cache path',
-  cacheList: 'list the currently cached versions',
-  cacheClear: 'delete the Cypress binary cache',
+  cachePath: 'print the path to the binary cache',
+  cacheList: 'list cached binary versions',
+  cacheClear: 'delete all cached binaries',
   group: 'a named group for recorded runs in the Cypress dashboard',
   parallel: 'enables concurrent runs and automatic load balancing of specs across multiple machines or processes',
   ciBuildId: 'the unique identifier for a run on your CI provider. typically a "BUILD_ID" env var. this value is automatically detected for most CI providers'
@@ -117,12 +149,16 @@ module.exports = {
 
     program.option('-v, --version', text('version')).command('version').description(text('version')).action(showVersions);
 
-    program.command('run').usage('[options]').description('Runs Cypress tests from the CLI without the GUI').option('--record [bool]', text('record'), coerceFalse).option('--headed', text('headed')).option('-k, --key <record-key>', text('key')).option('-s, --spec <spec>', text('spec')).option('-r, --reporter <reporter>', text('reporter')).option('-o, --reporter-options <reporter-options>', text('reporterOptions')).option('-p, --port <port>', text('port')).option('-e, --env <env>', text('env')).option('-c, --config <config>', text('config')).option('-b, --browser <browser-name>', text('browser')).option('-P, --project <project-path>', text('project')).option('--parallel', text('parallel')).option('--group <name>', text('group')).option('--ci-build-id <id>', text('ciBuildId')).option('--no-exit', text('exit')).option('--dev', text('dev'), coerceFalse).action(function (opts) {
+    program.command('run').usage('[options]').description('Runs Cypress tests from the CLI without the GUI').option('--record [bool]', text('record'), coerceFalse).option('--headed', text('headed')).option('-k, --key <record-key>', text('key')).option('-s, --spec <spec>', text('spec')).option('-r, --reporter <reporter>', text('reporter')).option('-o, --reporter-options <reporter-options>', text('reporterOptions')).option('-p, --port <port>', text('port')).option('-e, --env <env>', text('env')).option('-c, --config <config>', text('config')).option('-b, --browser <browser-name-or-path>', text('browserRunMode')).option('-P, --project <project-path>', text('project')).option('--parallel', text('parallel')).option('--group <name>', text('group')).option('--ci-build-id <id>', text('ciBuildId')).option('--no-exit', text('exit')).option('--dev', text('dev'), coerceFalse).action(function () {
+      for (var _len = arguments.length, fnArgs = Array(_len), _key = 0; _key < _len; _key++) {
+        fnArgs[_key] = arguments[_key];
+      }
+
       debug('running Cypress');
-      require('./exec/run').start(parseOpts(opts)).then(util.exit).catch(util.logErrorExit1);
+      require('./exec/run').start(parseVariableOpts(fnArgs, args)).then(util.exit).catch(util.logErrorExit1);
     });
 
-    program.command('open').usage('[options]').description('Opens Cypress in the interactive GUI.').option('-p, --port <port>', text('port')).option('-e, --env <env>', text('env')).option('-c, --config <config>', text('config')).option('-d, --detached [bool]', text('detached'), coerceFalse).option('-P, --project <project path>', text('project')).option('--global', text('global')).option('--dev', text('dev'), coerceFalse).action(function (opts) {
+    program.command('open').usage('[options]').description('Opens Cypress in the interactive GUI.').option('-p, --port <port>', text('port')).option('-e, --env <env>', text('env')).option('-c, --config <config>', text('config')).option('-d, --detached [bool]', text('detached'), coerceFalse).option('-b, --browser <browser-path>', text('browserOpenMode')).option('-P, --project <project-path>', text('project')).option('--global', text('global')).option('--dev', text('dev'), coerceFalse).action(function (opts) {
       debug('opening Cypress');
       require('./exec/open').start(parseOpts(opts)).catch(util.logErrorExit1);
     });
@@ -131,7 +167,7 @@ module.exports = {
       require('./tasks/install').start(parseOpts(opts)).catch(util.logErrorExit1);
     });
 
-    program.command('verify').usage('[options]').description('Verifies that Cypress is installed correctly and executable').action(function (opts) {
+    program.command('verify').usage('[options]').description('Verifies that Cypress is installed correctly and executable').option('--dev', text('dev'), coerceFalse).action(function (opts) {
       var defaultOpts = { force: true, welcomeMessage: false };
       var parsedOpts = parseOpts(opts);
       var options = _.extend(parsedOpts, defaultOpts);
@@ -140,8 +176,13 @@ module.exports = {
     });
 
     program.command('cache').usage('[command]').description('Manages the Cypress binary cache').option('list', text('cacheList')).option('path', text('cachePath')).option('clear', text('cacheClear')).action(function (opts) {
+      if (!_.isString(opts)) {
+        this.outputHelp();
+        util.exit(1);
+      }
+
       if (opts.command || !_.includes(['list', 'path', 'clear'], opts)) {
-        unknownOption.call(this, 'cache ' + opts, 'sub-command');
+        unknownOption.call(this, 'cache ' + opts, 'command');
       }
 
       cache[opts]();
@@ -157,8 +198,6 @@ module.exports = {
       // exits
     }
 
-    // Deprecated Catches
-
     var firstCommand = args[2];
 
     if (!_.includes(knownCommands, firstCommand)) {

package/lib/errors.js

@@ -2,18 +2,20 @@
 
 var _templateObject = _taggedTemplateLiteral(['\n    Search for an existing issue or open a GitHub issue at\n\n      ', '\n  '], ['\n    Search for an existing issue or open a GitHub issue at\n\n      ', '\n  ']),
     _templateObject2 = _taggedTemplateLiteral(['\n    \nPlease reinstall Cypress by running: ', '\n  '], ['\n    \\nPlease reinstall Cypress by running: ', '\n  ']),
-    _templateObject3 = _taggedTemplateLiteral(['\n\n    Reasons this may happen:\n      \n    - node was installed as \'root\' or with \'sudo\'\n    - the cypress npm package as \'root\' or with \'sudo\'\n    \n    Please check that you have the appropriate user permissions.\n  '], ['\\n\n    Reasons this may happen:\n      \n    - node was installed as \'root\' or with \'sudo\'\n    - the cypress npm package as \'root\' or with \'sudo\'\n    \n    Please check that you have the appropriate user permissions.\n  ']),
-    _templateObject4 = _taggedTemplateLiteral(['\n\n    We expected the binary to be installed here: ', '\n \n    Reasons it may be missing:\n\n    - You\'re caching \'node_modules\' but are not caching this path: ', '\n    - You ran \'npm install\' at an earlier build step but did not persist: ', '\n\n    Properly caching the binary will fix this error and avoid downloading and unzipping Cypress.\n\n    Alternatively, you can run \'cypress install\' to download the binary again.\n\n    ', '\n  '], ['\\n\n    We expected the binary to be installed here: ', '\n \n    Reasons it may be missing:\n\n    - You\'re caching \'node_modules\' but are not caching this path: ', '\n    - You ran \'npm install\' at an earlier build step but did not persist: ', '\n\n    Properly caching the binary will fix this error and avoid downloading and unzipping Cypress.\n\n    Alternatively, you can run \'cypress install\' to download the binary again.\n\n    ', '\n  ']),
+    _templateObject3 = _taggedTemplateLiteral(['\n\n    Reasons this may happen:\n\n    - node was installed as \'root\' or with \'sudo\'\n    - the cypress npm package as \'root\' or with \'sudo\'\n\n    Please check that you have the appropriate user permissions.\n  '], ['\\n\n    Reasons this may happen:\n\n    - node was installed as \'root\' or with \'sudo\'\n    - the cypress npm package as \'root\' or with \'sudo\'\n\n    Please check that you have the appropriate user permissions.\n  ']),
+    _templateObject4 = _taggedTemplateLiteral(['\n\n    We expected the binary to be installed here: ', '\n\n    Reasons it may be missing:\n\n    - You\'re caching \'node_modules\' but are not caching this path: ', '\n    - You ran \'npm install\' at an earlier build step but did not persist: ', '\n\n    Properly caching the binary will fix this error and avoid downloading and unzipping Cypress.\n\n    Alternatively, you can run \'cypress install\' to download the binary again.\n\n    ', '\n  '], ['\\n\n    We expected the binary to be installed here: ', '\n\n    Reasons it may be missing:\n\n    - You\'re caching \'node_modules\' but are not caching this path: ', '\n    - You ran \'npm install\' at an earlier build step but did not persist: ', '\n\n    Properly caching the binary will fix this error and avoid downloading and unzipping Cypress.\n\n    Alternatively, you can run \'cypress install\' to download the binary again.\n\n    ', '\n  ']),
     _templateObject5 = _taggedTemplateLiteral(['\n    There was a problem spawning Xvfb.\n\n    This is likely a problem with your system, permissions, or installation of Xvfb.\n    '], ['\n    There was a problem spawning Xvfb.\n\n    This is likely a problem with your system, permissions, or installation of Xvfb.\n    ']),
-    _templateObject6 = _taggedTemplateLiteral(['\n    Install XVFB and run Cypress again.\n\n    Read our documentation on dependencies for more information:\n\n      ', '\n\n    If you are using Docker, we provide containers with all required dependencies installed.\n    '], ['\n    Install XVFB and run Cypress again.\n\n    Read our documentation on dependencies for more information:\n\n      ', '\n\n    If you are using Docker, we provide containers with all required dependencies installed.\n    ']),
-    _templateObject7 = _taggedTemplateLiteral(['\n    This is usually caused by a missing library or dependency.\n\n    The error below should indicate which dependency is missing.\n\n      ', '\n\n    If you are using Docker, we provide containers with all required dependencies installed.\n  '], ['\n    This is usually caused by a missing library or dependency.\n\n    The error below should indicate which dependency is missing.\n\n      ', '\n\n    If you are using Docker, we provide containers with all required dependencies installed.\n  ']),
-    _templateObject8 = _taggedTemplateLiteral(['\n    Please search Cypress documentation for possible solutions:\n\n      ', '\n\n    Check if there is a GitHub issue describing this crash:\n\n      ', '\n\n    Consider opening a new issue.\n  '], ['\n    Please search Cypress documentation for possible solutions:\n\n      ', '\n\n    Check if there is a GitHub issue describing this crash:\n\n      ', '\n\n    Consider opening a new issue.\n  ']),
-    _templateObject9 = _taggedTemplateLiteral(['\n    The environment variable CYPRESS_BINARY_VERSION has been renamed to CYPRESS_INSTALL_BINARY as of version ', '\n    '], ['\n    The environment variable CYPRESS_BINARY_VERSION has been renamed to CYPRESS_INSTALL_BINARY as of version ', '\n    ']),
-    _templateObject10 = _taggedTemplateLiteral(['\n    You should set CYPRESS_INSTALL_BINARY instead.\n    '], ['\n    You should set CYPRESS_INSTALL_BINARY instead.\n    ']),
-    _templateObject11 = _taggedTemplateLiteral(['\n    The environment variable CYPRESS_SKIP_BINARY_INSTALL has been removed as of version ', '\n    '], ['\n    The environment variable CYPRESS_SKIP_BINARY_INSTALL has been removed as of version ', '\n    ']),
-    _templateObject12 = _taggedTemplateLiteral(['\n      To skip the binary install, set CYPRESS_INSTALL_BINARY=0\n    '], ['\n      To skip the binary install, set CYPRESS_INSTALL_BINARY=0\n    ']),
-    _templateObject13 = _taggedTemplateLiteral(['\n    Platform: ', ' (', ')\n    Cypress Version: ', '\n  '], ['\n    Platform: ', ' (', ')\n    Cypress Version: ', '\n  ']),
-    _templateObject14 = _taggedTemplateLiteral(['', ''], ['', '']);
+    _templateObject6 = _taggedTemplateLiteral(['\n    Install Xvfb and run Cypress again.\n\n    Read our documentation on dependencies for more information:\n\n      ', '\n\n    If you are using Docker, we provide containers with all required dependencies installed.\n    '], ['\n    Install Xvfb and run Cypress again.\n\n    Read our documentation on dependencies for more information:\n\n      ', '\n\n    If you are using Docker, we provide containers with all required dependencies installed.\n    ']),
+    _templateObject7 = _taggedTemplateLiteral(['\n    This command failed with the following output:\n\n    ', '\n\n    '], ['\n    This command failed with the following output:\n\n    ', '\n\n    ']),
+    _templateObject8 = _taggedTemplateLiteral(['\n      Cypress failed to start after spawning a new Xvfb server.\n\n      The error logs we received were:\n\n      ', '\n\n      ', '\n\n      ', '\n\n      This is usually caused by a missing library or dependency.\n\n      The error above should indicate which dependency is missing.\n\n        ', '\n\n      If you are using Docker, we provide containers with all required dependencies installed.\n    '], ['\n      Cypress failed to start after spawning a new Xvfb server.\n\n      The error logs we received were:\n\n      ', '\n\n      ', '\n\n      ', '\n\n      This is usually caused by a missing library or dependency.\n\n      The error above should indicate which dependency is missing.\n\n        ', '\n\n      If you are using Docker, we provide containers with all required dependencies installed.\n    ']),
+    _templateObject9 = _taggedTemplateLiteral(['\n    This is usually caused by a missing library or dependency.\n\n    The error below should indicate which dependency is missing.\n\n      ', '\n\n    If you are using Docker, we provide containers with all required dependencies installed.\n  '], ['\n    This is usually caused by a missing library or dependency.\n\n    The error below should indicate which dependency is missing.\n\n      ', '\n\n    If you are using Docker, we provide containers with all required dependencies installed.\n  ']),
+    _templateObject10 = _taggedTemplateLiteral(['\n    See discussion and possible solutions at\n    ', '\n  '], ['\n    See discussion and possible solutions at\n    ', '\n  ']),
+    _templateObject11 = _taggedTemplateLiteral(['\n    Please search Cypress documentation for possible solutions:\n\n      ', '\n\n    Check if there is a GitHub issue describing this crash:\n\n      ', '\n\n    Consider opening a new issue.\n  '], ['\n    Please search Cypress documentation for possible solutions:\n\n      ', '\n\n    Check if there is a GitHub issue describing this crash:\n\n      ', '\n\n    Consider opening a new issue.\n  ']),
+    _templateObject12 = _taggedTemplateLiteral(['\n    The environment variable CYPRESS_BINARY_VERSION has been renamed to CYPRESS_INSTALL_BINARY as of version ', '\n    '], ['\n    The environment variable CYPRESS_BINARY_VERSION has been renamed to CYPRESS_INSTALL_BINARY as of version ', '\n    ']),
+    _templateObject13 = _taggedTemplateLiteral(['\n    You should set CYPRESS_INSTALL_BINARY instead.\n    '], ['\n    You should set CYPRESS_INSTALL_BINARY instead.\n    ']),
+    _templateObject14 = _taggedTemplateLiteral(['\n    The environment variable CYPRESS_SKIP_BINARY_INSTALL has been removed as of version ', '\n    '], ['\n    The environment variable CYPRESS_SKIP_BINARY_INSTALL has been removed as of version ', '\n    ']),
+    _templateObject15 = _taggedTemplateLiteral(['\n      To skip the binary install, set CYPRESS_INSTALL_BINARY=0\n    '], ['\n      To skip the binary install, set CYPRESS_INSTALL_BINARY=0\n    ']),
+    _templateObject16 = _taggedTemplateLiteral(['\n    Platform: ', ' (', ')\n    Cypress Version: ', '\n  '], ['\n    Platform: ', ' (', ')\n    Cypress Version: ', '\n  ']);
 
 function _taggedTemplateLiteral(strings, raw) { return Object.freeze(Object.defineProperties(strings, { raw: { value: Object.freeze(raw) } })); }
 
@@ -27,13 +29,20 @@ var _require = require('common-tags'),
 var _require2 = require('ramda'),
     merge = _require2.merge;
 
+var la = require('lazy-ass');
+var is = require('check-more-types');
+
 var util = require('./util');
 var state = require('./tasks/state');
 
-var issuesUrl = 'https://github.com/cypress-io/cypress/issues';
 var docsUrl = 'https://on.cypress.io';
 var requiredDependenciesUrl = docsUrl + '/required-dependencies';
 
+// TODO it would be nice if all error objects could be enforced via types
+// to only have description + solution properties
+
+var hr = '----------';
+
 // common errors Cypress application can encounter
 var failedDownload = {
   description: 'The Cypress App could not be downloaded.',
@@ -42,7 +51,7 @@ var failedDownload = {
 
 var failedUnzip = {
   description: 'The Cypress App could not be unzipped.',
-  solution: stripIndent(_templateObject, chalk.blue(issuesUrl))
+  solution: stripIndent(_templateObject, chalk.blue(util.issuesUrl))
 };
 
 var missingApp = function missingApp(binaryDir) {
@@ -54,7 +63,7 @@ var missingApp = function missingApp(binaryDir) {
 
 var binaryNotExecutable = function binaryNotExecutable(executable) {
   return {
-    description: 'Cypress cannot run because the binary does not have executable permissions: ' + executable,
+    description: 'Cypress cannot run because this binary file does not have executable permissions here:\n\n' + executable,
     solution: stripIndent(_templateObject3)
   };
 };
@@ -67,24 +76,39 @@ var notInstalledCI = function notInstalledCI(executable) {
 };
 
 var nonZeroExitCodeXvfb = {
-  description: 'XVFB exited with a non zero exit code.',
+  description: 'Xvfb exited with a non zero exit code.',
   solution: stripIndent(_templateObject5)
 };
 
 var missingXvfb = {
-  description: 'Your system is missing the dependency: XVFB',
+  description: 'Your system is missing the dependency: Xvfb',
   solution: stripIndent(_templateObject6, chalk.blue(requiredDependenciesUrl))
 };
 
+var smokeTestFailure = function smokeTestFailure(smokeTestCommand, timedOut) {
+  return {
+    description: 'Cypress verification ' + (timedOut ? 'timed out' : 'failed') + '.',
+    solution: stripIndent(_templateObject7, smokeTestCommand)
+  };
+};
+
+var invalidSmokeTestDisplayError = {
+  code: 'INVALID_SMOKE_TEST_DISPLAY_ERROR',
+  description: 'Cypress verification failed.',
+  solution: function solution(msg) {
+    return stripIndent(_templateObject8, hr, msg, hr, chalk.blue(requiredDependenciesUrl));
+  }
+};
+
 var missingDependency = {
   description: 'Cypress failed to start.',
   // this message is too Linux specific
-  solution: stripIndent(_templateObject7, chalk.blue(requiredDependenciesUrl))
+  solution: stripIndent(_templateObject9, chalk.blue(requiredDependenciesUrl))
 };
 
 var invalidCacheDirectory = {
   description: 'Cypress cannot write to the cache directory due to file permissions',
-  solution: ''
+  solution: stripIndent(_templateObject10, chalk.blue(util.getGitHubIssueUrl(1281)))
 };
 
 var versionMismatch = {
@@ -94,17 +118,17 @@ var versionMismatch = {
 
 var unexpected = {
   description: 'An unexpected error occurred while verifying the Cypress executable.',
-  solution: stripIndent(_templateObject8, chalk.blue(docsUrl), chalk.blue(issuesUrl))
+  solution: stripIndent(_templateObject11, chalk.blue(docsUrl), chalk.blue(util.issuesUrl))
 };
 
 var removed = {
   CYPRESS_BINARY_VERSION: {
-    description: stripIndent(_templateObject9, chalk.green('3.0.0')),
-    solution: stripIndent(_templateObject10)
+    description: stripIndent(_templateObject12, chalk.green('3.0.0')),
+    solution: stripIndent(_templateObject13)
   },
   CYPRESS_SKIP_BINARY_INSTALL: {
-    description: stripIndent(_templateObject11, chalk.green('3.0.0')),
-    solution: stripIndent(_templateObject12)
+    description: stripIndent(_templateObject14, chalk.green('3.0.0')),
+    solution: stripIndent(_templateObject15)
   }
 };
 
@@ -113,7 +137,7 @@ var CYPRESS_RUN_BINARY = {
     var properFormat = '**/' + state.getPlatformExecutable();
 
     return {
-      description: 'Could not run binary set by environment variable CYPRESS_RUN_BINARY=' + value,
+      description: 'Could not run binary set by environment variable: CYPRESS_RUN_BINARY=' + value,
       solution: 'Ensure the environment variable is a path to the Cypress binary, matching ' + properFormat
     };
   }
@@ -121,7 +145,7 @@ var CYPRESS_RUN_BINARY = {
 
 function getPlatformInfo() {
   return util.getOsVersionAsync().then(function (version) {
-    return stripIndent(_templateObject13, os.platform(), version, util.pkgVersion());
+    return stripIndent(_templateObject16, os.platform(), version, util.pkgVersion());
   });
 }
 
@@ -131,20 +155,36 @@ function addPlatformInformation(info) {
   });
 }
 
-function formErrorText(info, msg) {
-  var hr = '----------';
-
+/**
+ * Forms nice error message with error and platform information,
+ * and if possible a way to solve it. Resolves with a string.
+ */
+function formErrorText(info, msg, prevMessage) {
   return addPlatformInformation(info).then(function (obj) {
     var formatted = [];
 
     function add(msg) {
-      formatted.push(stripIndents(_templateObject14, msg));
+      formatted.push(stripIndents(msg));
     }
 
-    add('\n      ' + obj.description + '\n\n      ' + obj.solution + '\n\n    ');
+    la(is.unemptyString(obj.description), 'expected error description to be text', obj.description);
+
+    // assuming that if there the solution is a function it will handle
+    // error message and (optional previous error message)
+    if (is.fn(obj.solution)) {
+      var text = obj.solution(msg, prevMessage);
+
+      la(is.unemptyString(text), 'expected solution to be text', text);
+
+      add('\n        ' + obj.description + '\n\n        ' + text + '\n\n      ');
+    } else {
+      la(is.unemptyString(obj.solution), 'expected error solution to be text', obj.solution);
 
-    if (msg) {
-      add('\n        ' + hr + '\n\n        ' + msg + '\n\n      ');
+      add('\n        ' + obj.description + '\n\n        ' + obj.solution + '\n\n      ');
+
+      if (msg) {
+        add('\n          ' + hr + '\n\n          ' + msg + '\n\n        ');
+      }
     }
 
     add('\n      ' + hr + '\n\n      ' + obj.platform + '\n    ');
@@ -153,34 +193,41 @@ function formErrorText(info, msg) {
       add('\n\n        ' + hr + '\n\n        ' + obj.footer + '\n      ');
     }
 
-    return formatted.join('\n');
+    return formatted.join('\n\n');
   });
 }
 
-var raise = function raise(text) {
-  var err = new Error(text);
+var raise = function raise(info) {
+  return function (text) {
+    var err = new Error(text);
+
+    if (info.code) {
+      err.code = info.code;
+    }
 
-  err.known = true;
-  throw err;
+    err.known = true;
+    throw err;
+  };
 };
 
 var throwFormErrorText = function throwFormErrorText(info) {
-  return function (msg) {
-    return formErrorText(info, msg).then(raise);
+  return function (msg, prevMessage) {
+    return formErrorText(info, msg, prevMessage).then(raise(info));
   };
 };
 
 module.exports = {
   raise: raise,
-  // formError,
   formErrorText: formErrorText,
   throwFormErrorText: throwFormErrorText,
+  hr: hr,
   errors: {
     nonZeroExitCodeXvfb: nonZeroExitCodeXvfb,
     missingXvfb: missingXvfb,
     missingApp: missingApp,
     notInstalledCI: notInstalledCI,
     missingDependency: missingDependency,
+    invalidSmokeTestDisplayError: invalidSmokeTestDisplayError,
     versionMismatch: versionMismatch,
     binaryNotExecutable: binaryNotExecutable,
     unexpected: unexpected,
@@ -188,6 +235,7 @@ module.exports = {
     failedUnzip: failedUnzip,
     invalidCacheDirectory: invalidCacheDirectory,
     removed: removed,
-    CYPRESS_RUN_BINARY: CYPRESS_RUN_BINARY
+    CYPRESS_RUN_BINARY: CYPRESS_RUN_BINARY,
+    smokeTestFailure: smokeTestFailure
   }
 };

package/lib/exec/open.js

@@ -23,6 +23,10 @@ module.exports = {
       args.push('--config', options.config);
     }
 
+    if (options.browser) {
+      args.push('--browser', options.browser);
+    }
+
     if (options.port) {
       args.push('--port', options.port);
     }

package/lib/exec/spawn.js

@@ -6,6 +6,7 @@ var cp = require('child_process');
 var path = require('path');
 var Promise = require('bluebird');
 var debug = require('debug')('cypress:cli');
+var debugElectron = require('debug')('cypress:electron');
 
 var util = require('../util');
 var state = require('../tasks/state');
@@ -18,12 +19,20 @@ var _require = require('../errors'),
 var isXlibOrLibudevRe = /^(?:Xlib|libudev)/;
 var isHighSierraWarningRe = /\*\*\* WARNING/;
 
+var GARBAGE_WARNINGS = [isXlibOrLibudevRe, isHighSierraWarningRe];
+
+var isGarbageLineWarning = function isGarbageLineWarning(str) {
+  return _.some(GARBAGE_WARNINGS, function (re) {
+    return re.test(str);
+  });
+};
+
 function isPlatform(platform) {
   return os.platform() === platform;
 }
 
 function needsStderrPiped(needsXvfb) {
-  return isPlatform('darwin') || needsXvfb && isPlatform('linux');
+  return _.some([isPlatform('darwin'), needsXvfb && isPlatform('linux'), util.isPossibleLinuxWithIncorrectDisplay()]);
 }
 
 function needsEverythingPipedDirectly() {
@@ -41,7 +50,7 @@ function getStdio(needsXvfb) {
   if (needsStderrPiped(needsXvfb)) {
     // returning pipe here so we can massage stderr
     // and remove garbage from Xlib and libuv
-    // due to starting the XVFB process on linux
+    // due to starting the Xvfb process on linux
     return ['inherit', 'inherit', 'pipe'];
   }
 
@@ -59,19 +68,27 @@ module.exports = {
       executable = path.resolve(util.getEnv('CYPRESS_RUN_BINARY'));
     }
 
-    debug('needs XVFB?', needsXvfb);
+    debug('needs to start own Xvfb?', needsXvfb);
 
     // always push cwd into the args
     args = [].concat(args, '--cwd', process.cwd());
 
     _.defaults(options, {
+      dev: false,
       env: process.env,
       detached: false,
       stdio: getStdio(needsXvfb)
     });
 
     var spawn = function spawn() {
+      var overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+
       return new Promise(function (resolve, reject) {
+        _.defaults(overrides, {
+          onStderrData: false,
+          electronLogging: false
+        });
+
         if (options.dev) {
           // if we're in dev then reset
           // the launch cmd to be 'npm run dev'
@@ -79,26 +96,39 @@ module.exports = {
           args.unshift(path.resolve(__dirname, '..', '..', '..', 'scripts', 'start.js'));
         }
 
-        var overrides = util.getEnvOverrides();
-        var node11WindowsFix = isPlatform('win32');
+        var onStderrData = overrides.onStderrData,
+            electronLogging = overrides.electronLogging;
 
-        debug('spawning Cypress with executable: %s', executable);
-        debug('spawn forcing env overrides %o', overrides);
-        debug('spawn args %o %o', args, _.omit(options, 'env'));
+        var envOverrides = util.getEnvOverrides();
+        var electronArgs = _.clone(args);
+        var node11WindowsFix = isPlatform('win32');
 
         // strip dev out of child process options
-        options = _.omit(options, 'dev');
-        options = _.omit(options, 'binaryFolder');
+        var stdioOptions = _.pick(options, 'env', 'detached', 'stdio');
 
         // figure out if we're going to be force enabling or disabling colors.
         // also figure out whether we should force stdout and stderr into thinking
         // it is a tty as opposed to a pipe.
-        options.env = _.extend({}, options.env, overrides);
+        stdioOptions.env = _.extend({}, stdioOptions.env, envOverrides);
+
         if (node11WindowsFix) {
-          options = _.extend({}, options, { windowsHide: false });
+          stdioOptions = _.extend({}, stdioOptions, { windowsHide: false });
+        }
+
+        if (electronLogging) {
+          stdioOptions.env.ELECTRON_ENABLE_LOGGING = true;
         }
 
-        var child = cp.spawn(executable, args, options);
+        if (util.isPossibleLinuxWithIncorrectDisplay()) {
+          // make sure we use the latest DISPLAY variable if any
+          debug('passing DISPLAY', process.env.DISPLAY);
+          stdioOptions.env.DISPLAY = process.env.DISPLAY;
+        }
+
+        debug('spawning Cypress with executable: %s', executable);
+        debug('spawn args %o %o', electronArgs, _.omit(stdioOptions, 'env'));
+
+        var child = cp.spawn(executable, electronArgs, stdioOptions);
 
         child.on('close', resolve);
         child.on('error', reject);
@@ -112,7 +142,13 @@ module.exports = {
           var str = data.toString();
 
           // bail if this is warning line garbage
-          if (isXlibOrLibudevRe.test(str) || isHighSierraWarningRe.test(str)) {
+          if (isGarbageLineWarning(str)) {
+            return;
+          }
+
+          // if we have a callback and this explictly returns
+          // false then bail
+          if (onStderrData && onStderrData(str) === false) {
             return;
           }
 
@@ -134,20 +170,63 @@ module.exports = {
           throw err;
         });
 
-        if (options.detached) {
+        if (stdioOptions.detached) {
           child.unref();
         }
       });
     };
 
-    var userFriendlySpawn = function userFriendlySpawn() {
-      return spawn().catch(throwFormErrorText(errors.unexpected));
+    var spawnInXvfb = function spawnInXvfb() {
+      return xvfb.start().then(userFriendlySpawn).finally(xvfb.stop);
+    };
+
+    var userFriendlySpawn = function userFriendlySpawn(linuxWithDisplayEnv) {
+      debug('spawning, should retry on display problem?', Boolean(linuxWithDisplayEnv));
+
+      var brokenGtkDisplay = void 0;
+
+      var overrides = {};
+
+      if (linuxWithDisplayEnv) {
+        _.extend(overrides, {
+          electronLogging: true,
+          onStderrData: function onStderrData(str) {
+            // if we receive a broken pipe anywhere
+            // then we know that's why cypress exited early
+            if (util.isBrokenGtkDisplay(str)) {
+              brokenGtkDisplay = true;
+            }
+
+            // we should attempt to always slurp up
+            // the stderr logs unless we've explicitly
+            // enabled the electron debug logging
+            if (!debugElectron.enabled) {
+              return false;
+            }
+          }
+        });
+      }
+
+      return spawn(overrides).then(function (code) {
+        if (code !== 0 && brokenGtkDisplay) {
+          util.logBrokenGtkDisplayWarning();
+
+          return spawnInXvfb();
+        }
+
+        return code;
+      }).catch(throwFormErrorText(errors.unexpected));
     };
 
     if (needsXvfb) {
-      return xvfb.start().then(userFriendlySpawn).finally(xvfb.stop);
+      return spawnInXvfb();
     }
 
-    return userFriendlySpawn();
+    // if we are on linux and there's already a DISPLAY
+    // set, then we may need to rerun cypress after
+    // spawning our own Xvfb server
+    var linuxWithDisplayEnv = util.isPossibleLinuxWithIncorrectDisplay();
+
+    return userFriendlySpawn(linuxWithDisplayEnv);
   }
 };