|
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