Skip to content

Commit c5bb08c

Browse files
authored
docs: remove outdated troubleshooting (#4706)
Most of the troubleshooting.md doc is not relevant any more: - dependencies are maintained and helped with by launch doctor - sandbox is disabled in Chromium by default References #4683
1 parent 8d574a7 commit c5bb08c

File tree

1 file changed

+5
-174
lines changed

1 file changed

+5
-174
lines changed

docs/troubleshooting.md

Lines changed: 5 additions & 174 deletions
Original file line numberDiff line numberDiff line change
@@ -1,187 +1,18 @@
11
# Troubleshooting
22

33
<!-- 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)
125
- [Code transpilation issues](#code-transpilation-issues)
136
- [Node.js requirements](#nodejs-requirements)
147
* [ReferenceError: URL is not defined](#referenceerror-url-is-not-defined)
158
<!-- GEN:stop -->
169

17-
## Chromium
10+
## Browser dependencies
1811

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.
2014

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.
18516

18617
## Code transpilation issues
18718

0 commit comments

Comments
 (0)