fix: re-write Chromium startup error with clear instructions (#3070)

This patch detects Chromium crash with a sandboxing error and re-writes
the error to surface information nicely.

#### Error Before:

```sh
pwuser@23592d09b3bd:~/tmp$ node a.js
(node:324) UnhandledPromiseRejectionWarning: browserType.launch: Protocol error (Browser.getVersion): Target closed.
=========================== logs ===========================
[browser] <launching> /home/pwuser/.cache/ms-playwright/chromium-790602/chrome-linux/chrome --disable-background-networking --enable-features=NetworkService,NetworkServiceInProcess --disable-background-timer-throttling --disable-backgrounding-occluded-windows --disable-breakpad --disab
le-client-side-phishing-detection --disable-component-extensions-with-background-pages --disable-default-apps --disable-dev-shm-usage --disable-extensions --disable-features=TranslateUI,BlinkGenPropertyTrees,ImprovedCookieControls,SameSiteByDefaultCookies --disable-hang-monitor --disab
le-ipc-flooding-protection --disable-popup-blocking --disable-prompt-on-repost --disable-renderer-backgrounding --disable-sync --force-color-profile=srgb --metrics-recording-only --no-first-run --enable-automation --password-store=basic --use-mock-keychain --user-data-dir=/tmp/playwrig
ht_chromiumdev_profile-mjSfr2 --remote-debugging-pipe --headless --hide-scrollbars --mute-audio --no-startup-window
[browser] <launched> pid=401
[browser] [0722/170825.030020:FATAL:zygote_host_impl_linux.cc(117)] No usable sandbox! Update your kernel or see https://chromium.googlesource.com/chromium/src/+/master/docs/linux/suid_sandbox_development.md for more information on developing with the SUID sandbox. If you want to live
dangerously and need an immediate workaround, you can try using --no-sandbox.
[browser] #0 0x55ac4f8c7be9 base::debug::CollectStackTrace()
[browser] #1 0x55ac4f841c13 base::debug::StackTrace::StackTrace()
[browser] #2 0x55ac4f853680 logging::LogMessage::~LogMessage()
[browser] #3 0x55ac4df2307e content::ZygoteHostImpl::Init()
[browser] #4 0x55ac4f40dd47 content::ContentMainRunnerImpl::Initialize()
[browser] #5 0x55ac4f45c9fa service_manager::Main()
[browser] #6 0x55ac4f40c361 content::ContentMain()
[browser] #7 0x55ac4f45b5bd headless::(anonymous namespace)::RunContentMain()
[browser] #8 0x55ac4f45b2bc headless::HeadlessShellMain()
[browser] #9 0x55ac4ccc22e7 ChromeMain
[browser] #10 0x7f0f3d736b97 __libc_start_main
[browser] #11 0x55ac4ccc212a _start
[browser]
[browser] Received signal 6
[browser] #0 0x55ac4f8c7be9 base::debug::CollectStackTrace()
[browser] #1 0x55ac4f841c13 base::debug::StackTrace::StackTrace()
[browser] #2 0x55ac4f8c7785 base::debug::(anonymous namespace)::StackDumpSignalHandler()
[browser] #3 0x7f0f437b3890 (/lib/x86_64-linux-gnu/libpthread-2.27.so+0x1288f)
[browser] #4 0x7f0f3d753e97 gsignal
[browser] #5 0x7f0f3d755801 abort
[browser] #6 0x55ac4f8c66e5 base::debug::BreakDebugger()
[browser] #7 0x55ac4f853aeb logging::LogMessage::~LogMessage()
[browser] #8 0x55ac4df2307e content::ZygoteHostImpl::Init()
[browser] #9 0x55ac4f40dd47 content::ContentMainRunnerImpl::Initialize()
[browser] #10 0x55ac4f45c9fa service_manager::Main()
[browser] #11 0x55ac4f40c361 content::ContentMain()
[browser] #12 0x55ac4f45b5bd headless::(anonymous namespace)::RunContentMain()
[browser] #13 0x55ac4f45b2bc headless::HeadlessShellMain()
[browser] #14 0x55ac4ccc22e7 ChromeMain
[browser] #15 0x7f0f3d736b97 __libc_start_main
[browser] #16 0x55ac4ccc212a _start
[browser]   r8: 0000000000000000  r9: 00007ffd38a863b0 r10: 0000000000000008 r11: 0000000000000246
[browser]  r12: 00007ffd38a87680 r13: 00007ffd38a86610 r14: 00007ffd38a87690 r15: aaaaaaaaaaaaaaaa
[browser]   di: 0000000000000002  si: 00007ffd38a863b0  bp: 00007ffd38a86600  bx: 00007ffd38a86e44
[browser]   dx: 0000000000000000  ax: 0000000000000000  cx: 00007f0f3d753e97  sp: 00007ffd38a863b0
[browser]   ip: 00007f0f3d753e97 efl: 0000000000000246 cgf: 002b000000000033 erf: 0000000000000000
[browser]  trp: 0000000000000000 msk: 0000000000000000 cr2: 0000000000000000
[browser] [end of stack trace]
[browser] Calling _exit(1). Core file will not be generated.
============================================================
Note: use DEBUG=pw:api environment variable and rerun to capture Playwright logs.Error
    at /home/pwuser/tmp/node_modules/playwright/lib/chromium/crConnection.js:131:63
    at new Promise (<anonymous>)
    at CRSession.send (/home/pwuser/tmp/node_modules/playwright/lib/chromium/crConnection.js:130:16)
    at CRSession.send (/home/pwuser/tmp/node_modules/playwright/lib/helper.js:78:31)
    at Function.connect (/home/pwuser/tmp/node_modules/playwright/lib/chromium/crBrowser.js:54:39)
    at Chromium._connectToTransport (/home/pwuser/tmp/node_modules/playwright/lib/server/chromium.js:52:38)
    at Chromium._innerLaunch (/home/pwuser/tmp/node_modules/playwright/lib/server/browserType.js:87:36)
    at async ProgressController.run (/home/pwuser/tmp/node_modules/playwright/lib/progress.js:75:28)
    at async Chromium.launch (/home/pwuser/tmp/node_modules/playwright/lib/server/browserType.js:60:25)
    at async /home/pwuser/tmp/a.js:4:19
(node:324) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise reject
ion, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 2)
(node:324) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.
```


#### Error After:

```sh
pwuser@23592d09b3bd:~/tmp$ node a.js
(node:222) UnhandledPromiseRejectionWarning: browserType.launch: Chromium sandboxing failed!
================================
To workaround sandboxing issues, do either of the following:
  - (preferred): Configure environment to support sandboxing: https://github.com/microsoft/playwright/blob/master/docs/troubleshooting.md
  - (alternative): Launch Chromium without sandbox using 'chromiumSandbox: false' option
================================
Error
    at /home/pwuser/tmp/node_modules/playwright/lib/chromium/crConnection.js:131:63
    at new Promise (<anonymous>)
    at CRSession.send (/home/pwuser/tmp/node_modules/playwright/lib/chromium/crConnection.js:130:16)
    at CRSession.send (/home/pwuser/tmp/node_modules/playwright/lib/helper.js:78:31)
    at Function.connect (/home/pwuser/tmp/node_modules/playwright/lib/chromium/crBrowser.js:54:27)
    at Chromium._connectToTransport (/home/pwuser/tmp/node_modules/playwright/lib/server/chromium.js:53:38)
    at Chromium._innerLaunch (/home/pwuser/tmp/node_modules/playwright/lib/server/browserType.js:89:36)
    at async ProgressController.run (/home/pwuser/tmp/node_modules/playwright/lib/progress.js:75:28)
    at async Chromium.launch (/home/pwuser/tmp/node_modules/playwright/lib/server/browserType.js:61:25)
    at async /home/pwuser/tmp/a.js:4:19
(node:222) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise reject
ion, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 2)
(node:222) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.
```

References #2745

Author: aslushnikov

src/server/browserType.ts

@@ -90,7 +90,8 @@ export abstract class BrowserTypeBase implements BrowserType {
     assert(!(options as any).port, 'Cannot specify a port without launching as a server.');
     options = validateLaunchOptions(options);
     const loggers = new Loggers(options.logger);
-    const browser = await runAbortableTask(progress => this._innerLaunch(progress, options, loggers, undefined), loggers.browser, TimeoutSettings.timeout(options), `browserType.launch`);
+    const label = 'browserType.launch';
+    const browser = await runAbortableTask(progress => this._innerLaunch(progress, options, loggers, undefined), loggers.browser, TimeoutSettings.timeout(options), label).catch(e => { throw this._rewriteStartupError(e, label); });
     return browser;
   }
 
@@ -99,7 +100,8 @@ export abstract class BrowserTypeBase implements BrowserType {
     options = validateLaunchOptions(options);
     const persistent = validateBrowserContextOptions(options);
     const loggers = new Loggers(options.logger);
-    const browser = await runAbortableTask(progress => this._innerLaunch(progress, options, loggers, persistent, userDataDir), loggers.browser, TimeoutSettings.timeout(options), 'browserType.launchPersistentContext');
+    const label = 'browserType.launchPersistentContext';
+    const browser = await runAbortableTask(progress => this._innerLaunch(progress, options, loggers, persistent, userDataDir), loggers.browser, TimeoutSettings.timeout(options), label).catch(e => { throw this._rewriteStartupError(e, label); });
     return browser._defaultContext!;
   }
 
@@ -240,6 +242,7 @@ export abstract class BrowserTypeBase implements BrowserType {
   abstract _startWebSocketServer(transport: ConnectionTransport, logger: Logger, port: number): WebSocketServer;
   abstract _amendEnvironment(env: Env, userDataDir: string, executable: string, browserArguments: string[]): Env;
   abstract _amendArguments(browserArguments: string[]): string[];
+  abstract _rewriteStartupError(error: Error, prefix: string): Error;
   abstract _attemptToGracefullyCloseBrowser(transport: ConnectionTransport): void;
 }
 

src/server/chromium.ts

@@ -22,6 +22,7 @@ import { CRBrowser } from '../chromium/crBrowser';
 import * as ws from 'ws';
 import { Env } from './processLauncher';
 import { kBrowserCloseMessageId } from '../chromium/crConnection';
+import { rewriteErrorMessage } from '../utils/stackTrace';
 import { BrowserTypeBase } from './browserType';
 import { ConnectionTransport, ProtocolRequest, ProtocolResponse } from '../transport';
 import { Logger } from '../logger';
@@ -63,6 +64,22 @@ export class Chromium extends BrowserTypeBase {
     return CRBrowser.connect(transport, options, devtools);
   }
 
+  _rewriteStartupError(error: Error, prefix: string): Error {
+    // These error messages are taken from Chromium source code as of July, 2020:
+    // https://github.com/chromium/chromium/blob/70565f67e79f79e17663ad1337dc6e63ee207ce9/content/browser/zygote_host/zygote_host_impl_linux.cc
+    if (!error.message.includes('crbug.com/357670') && !error.message.includes('No usable sandbox!') && !error.message.includes('crbug.com/638180'))
+      return error;
+    return rewriteErrorMessage(error, [
+      `${prefix}: Chromium sandboxing failed!`,
+      `================================`,
+      `To workaround sandboxing issues, do either of the following:`,
+      `  - (preferred): Configure environment to support sandboxing: https://github.com/microsoft/playwright/blob/master/docs/troubleshooting.md`,
+      `  - (alternative): Launch Chromium without sandbox using 'chromiumSandbox: false' option`,
+      `================================`,
+      ``,
+    ].join('\n'));
+  }
+
   _amendEnvironment(env: Env, userDataDir: string, executable: string, browserArguments: string[]): Env {
     return env;
   }
@@ -71,6 +88,7 @@ export class Chromium extends BrowserTypeBase {
     // We currently only support Linux.
     if (os.platform() !== 'linux')
       return browserArguments;
+
     // If there's already --no-sandbox passed in, do nothing.
     if (browserArguments.indexOf('--no-sandbox') !== -1)
       return browserArguments;

src/server/firefox.ts

@@ -39,6 +39,10 @@ export class Firefox extends BrowserTypeBase {
     return FFBrowser.connect(transport, options);
   }
 
+  _rewriteStartupError(error: Error, prefix: string): Error {
+    return error;
+  }
+
   _amendEnvironment(env: Env, userDataDir: string, executable: string, browserArguments: string[]): Env {
     return os.platform() === 'linux' ? {
       ...env,

src/server/webkit.ts

@@ -46,6 +46,10 @@ export class WebKit extends BrowserTypeBase {
     return browserArguments;
   }
 
+  _rewriteStartupError(error: Error, prefix: string): Error {
+    return error;
+  }
+
   _attemptToGracefullyCloseBrowser(transport: ConnectionTransport): void {
     transport.send({method: 'Playwright.close', params: {}, id: kBrowserCloseMessageId});
   }