|
1 | 1 | # Troubleshooting
|
2 | 2 |
|
3 | 3 | <!-- GEN:toc -->
|
4 |
| -- [Chromium](#chromium) |
5 |
| - * [Chrome headless doesn't launch on Windows](#chrome-headless-doesnt-launch-on-windows) |
6 |
| - * [Chrome headless doesn't launch on Linux/WSL](#chrome-headless-doesnt-launch-on-linuxwsl) |
7 |
| - * [Setting Up Chrome Linux Sandbox](#setting-up-chrome-linux-sandbox) |
8 |
| -- [Firefox](#firefox) |
9 |
| - * [Firefox headless doesn't launch on Linux/WSL](#firefox-headless-doesnt-launch-on-linuxwsl) |
10 |
| -- [WebKit](#webkit) |
11 |
| - * [WebKit headless doesn't launch on Linux/WSL](#webkit-headless-doesnt-launch-on-linuxwsl) |
| 4 | +- [Browser dependencies](#browser-dependencies) |
12 | 5 | - [Code transpilation issues](#code-transpilation-issues)
|
13 | 6 | - [Node.js requirements](#nodejs-requirements)
|
14 | 7 | * [ReferenceError: URL is not defined](#referenceerror-url-is-not-defined)
|
15 | 8 | <!-- GEN:stop -->
|
16 | 9 |
|
17 |
| -## Chromium |
| 10 | +## Browser dependencies |
18 | 11 |
|
19 |
| -### Chrome headless doesn't launch on Windows |
| 12 | +Playwright does self-inspection every time it runs to make sure the browsers can be launched successfully. If there are missing |
| 13 | +dependencies, playwright will print instructions to acquire them. |
20 | 14 |
|
21 |
| -Some [chrome policies](https://support.google.com/chrome/a/answer/7532015?hl=en) might enforce running Chrome/Chromium |
22 |
| -with certain extensions. |
23 |
| - |
24 |
| -Playwright passes `--disable-extensions` flag by default and will fail to launch when such policies are active. |
25 |
| - |
26 |
| -To work around this, try running without the flag: |
27 |
| - |
28 |
| -```js |
29 |
| -const browser = await playwright.chromium.launch({ |
30 |
| - ignoreDefaultArgs: ['--disable-extensions'], |
31 |
| -}); |
32 |
| -``` |
33 |
| - |
34 |
| -> Context: [Puppeteer#3681](https://github.com/puppeteer/puppeteer/issues/3681#issuecomment-447865342). |
35 |
| -
|
36 |
| -### Chrome headless doesn't launch on Linux/WSL |
37 |
| - |
38 |
| -Make sure all the necessary dependencies are installed. You can run `ldd chrome | grep not` on a Linux |
39 |
| -machine to check which dependencies are missing. For dependencies on Ubuntu, please refer to [Dockerfile](https://github.com/microsoft/playwright/blob/master/docs/docker/Dockerfile.bionic) which is used to run our tests. |
40 |
| - |
41 |
| -The common ones for Debian and CentOS are provided below. |
42 |
| - |
43 |
| -<details> |
44 |
| -<summary>Debian (e.g. Ubuntu) Dependencies</summary> |
45 |
| - |
46 |
| -``` |
47 |
| -gconf-service |
48 |
| -libasound2 |
49 |
| -libatk1.0-0 |
50 |
| -libatk-bridge2.0-0 |
51 |
| -libc6 |
52 |
| -libcairo2 |
53 |
| -libcups2 |
54 |
| -libdbus-1-3 |
55 |
| -libexpat1 |
56 |
| -libfontconfig1 |
57 |
| -libgcc1 |
58 |
| -libgconf-2-4 |
59 |
| -libgdk-pixbuf2.0-0 |
60 |
| -libglib2.0-0 |
61 |
| -libgtk-3-0 |
62 |
| -libnspr4 |
63 |
| -libpango-1.0-0 |
64 |
| -libpangocairo-1.0-0 |
65 |
| -libstdc++6 |
66 |
| -libx11-6 |
67 |
| -libx11-xcb1 |
68 |
| -libxcb1 |
69 |
| -libxcomposite1 |
70 |
| -libxcursor1 |
71 |
| -libxdamage1 |
72 |
| -libxext6 |
73 |
| -libxfixes3 |
74 |
| -libxi6 |
75 |
| -libxrandr2 |
76 |
| -libxrender1 |
77 |
| -libxss1 |
78 |
| -libxtst6 |
79 |
| -ca-certificates |
80 |
| -fonts-liberation |
81 |
| -libappindicator1 |
82 |
| -libnss3 |
83 |
| -lsb-release |
84 |
| -xdg-utils |
85 |
| -wget |
86 |
| -libgbm1 |
87 |
| -``` |
88 |
| -</details> |
89 |
| - |
90 |
| -<details> |
91 |
| -<summary>CentOS Dependencies</summary> |
92 |
| - |
93 |
| -``` |
94 |
| -pango.x86_64 |
95 |
| -libXcomposite.x86_64 |
96 |
| -libXcursor.x86_64 |
97 |
| -libXdamage.x86_64 |
98 |
| -libXext.x86_64 |
99 |
| -libXi.x86_64 |
100 |
| -libXtst.x86_64 |
101 |
| -cups-libs.x86_64 |
102 |
| -libXScrnSaver.x86_64 |
103 |
| -libXrandr.x86_64 |
104 |
| -GConf2.x86_64 |
105 |
| -alsa-lib.x86_64 |
106 |
| -atk.x86_64 |
107 |
| -gtk3.x86_64 |
108 |
| -ipa-gothic-fonts |
109 |
| -xorg-x11-fonts-100dpi |
110 |
| -xorg-x11-fonts-75dpi |
111 |
| -xorg-x11-utils |
112 |
| -xorg-x11-fonts-cyrillic |
113 |
| -xorg-x11-fonts-Type1 |
114 |
| -xorg-x11-fonts-misc |
115 |
| -``` |
116 |
| - |
117 |
| -After installing dependencies you need to update nss library using this command |
118 |
| - |
119 |
| -``` |
120 |
| -yum update nss -y |
121 |
| -``` |
122 |
| -</details> |
123 |
| - |
124 |
| -<details> |
125 |
| - <summary>Check out discussions</summary> |
126 |
| - |
127 |
| -- [Puppeteer#290](https://github.com/puppeteer/puppeteer/issues/290) - Debian troubleshooting <br/> |
128 |
| -- [Puppeteer#391](https://github.com/puppeteer/puppeteer/issues/391) - CentOS troubleshooting <br/> |
129 |
| -- [Puppeteer#379](https://github.com/puppeteer/puppeteer/issues/379) - Alpine troubleshooting <br/> |
130 |
| -</details> |
131 |
| - |
132 |
| -Please file new issues in this repo for things relating to Playwright. |
133 |
| - |
134 |
| -### Setting Up Chrome Linux Sandbox |
135 |
| - |
136 |
| -In order to protect the host environment from untrusted web content, Chrome uses [multiple layers of sandboxing](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux_sandboxing.md). For this to work properly, |
137 |
| -the host should be configured first. If there's no good sandbox for Chrome to use, it will crash |
138 |
| -with the error `No usable sandbox!`. |
139 |
| - |
140 |
| -If you **absolutely trust** the content you open in Chrome, you can launch Chrome |
141 |
| -with the `chromiumSandbox: false` option: |
142 |
| - |
143 |
| -```js |
144 |
| -const browser = await playwright.chromium.launch({ chromiumSandbox: false }); |
145 |
| -``` |
146 |
| - |
147 |
| -> **NOTE**: Running without a sandbox is **strongly discouraged**. Consider configuring a sandbox instead. |
148 |
| -
|
149 |
| -To enable Chromium sandbox, you should enable [user namespace cloning](http://man7.org/linux/man-pages/man7/user_namespaces.7.html). |
150 |
| - |
151 |
| -User namespace cloning is only supported by modern kernels. Unprivileged user |
152 |
| -namespaces are generally fine to enable, but in some cases they open up more |
153 |
| -kernel attack surface for (unsandboxed) non-root processes to elevate to kernel |
154 |
| -privileges. |
155 |
| - |
156 |
| -In general, user namespace cloning can be enabled with the following command: |
157 |
| - |
158 |
| -```bash |
159 |
| -sudo sysctl -w kernel.unprivileged_userns_clone=1 |
160 |
| -``` |
161 |
| - |
162 |
| -In case of Docker, containers need to be run with a custom [security profile](https://docs.docker.com/engine/security/seccomp/) that enables |
163 |
| -user namespace cloning. You can download this profile here: [`seccomp_profile.json`](docker/seccomp_profile.json) |
164 |
| - |
165 |
| -With the downloaded profile, docker container could be run like this: |
166 |
| - |
167 |
| -```sh |
168 |
| -docker run --rm --security-opt seccomp=/path/to/seccomp/profile.json -it my-image-name |
169 |
| -``` |
170 |
| - |
171 |
| - |
172 |
| -## Firefox |
173 |
| - |
174 |
| -### Firefox headless doesn't launch on Linux/WSL |
175 |
| - |
176 |
| -Make sure all the necessary dependencies are installed. You can run `ldd chrome | grep not` on a Linux |
177 |
| -machine to check which dependencies are missing. For dependencies on Ubuntu, please refer to [Dockerfile](https://github.com/microsoft/playwright/blob/master/docs/docker/Dockerfile.bionic) which is used to run our tests. |
178 |
| - |
179 |
| -## WebKit |
180 |
| - |
181 |
| -### WebKit headless doesn't launch on Linux/WSL |
182 |
| - |
183 |
| -Make sure all the necessary dependencies are installed. You can run `ldd chrome | grep not` on a Linux |
184 |
| -machine to check which dependencies are missing. For dependencies on Ubuntu, please refer to [Dockerfile](https://github.com/microsoft/playwright/blob/master/docs/docker/Dockerfile.bionic) which is used to run our tests. |
| 15 | +We also provide [Ubuntu 18.04 dockerfile](docker/Dockerfile.bionic) and [Ubuntu 20.04 dockerfile](docker/Dockerfile.focal) with the list of Debian dependencies. |
185 | 16 |
|
186 | 17 | ## Code transpilation issues
|
187 | 18 |
|
|
0 commit comments