# Puppeteer browsers

Avrea caches Chrome for Testing archives downloaded by Puppeteer. Repeated
downloads of the same version, platform, and archive use the packages cache.

## On Avrea runners

When **Package Manager Cache** and **Puppeteer Browser Cache** are enabled,
Avrea configures both download bases:

```bash
PUPPETEER_CHROME_DOWNLOAD_BASE_URL="https://cache.avrea.com:8443/puppeteer/chrome"
PUPPETEER_CHROME_HEADLESS_SHELL_DOWNLOAD_BASE_URL="https://cache.avrea.com:8443/puppeteer/chrome"
```

Use your normal Puppeteer installation. Its install script honors these
browser-specific environment variables:

```yaml
- run: npm ci
```

If your package manager blocks install scripts, install the browsers explicitly.
In Puppeteer 25.10.0, the browser CLI requires `--base-url` to use the same mirror.
Name each browser so its download base applies only to that browser:

```yaml
- run: |
    npx puppeteer browsers install chrome --base-url="$PUPPETEER_CHROME_DOWNLOAD_BASE_URL"
    npx puppeteer browsers install chrome-headless-shell --base-url="$PUPPETEER_CHROME_HEADLESS_SHELL_DOWNLOAD_BASE_URL"
```

## What is cached

Avrea caches download archives for Chrome and Chrome headless shell.
Puppeteer extracts them on each fresh runner. Its npm dependencies use the
[npm cache](/cache/packages/npm/).

## Enable or disable

**Puppeteer Browser Cache** (`cache.puppeteer-browsers.enabled`) is enabled by
default. Turn it on or off at organization or repository level under
**Settings** in the [Avrea console](https://console.avrea.com). **Package Manager
Cache** (`cache.packages.enabled`) must also be enabled.

Disable it for a repository:

```bash
avr settings set cache.puppeteer-browsers.enabled false
```

Re-enable it:

```bash
avr settings set cache.puppeteer-browsers.enabled true
```

Reset to the inherited default:

```bash
avr settings reset cache.puppeteer-browsers.enabled
```

Repository overrides take precedence over organization settings. Resetting the
repository setting restores inheritance. See [Managing caches](/cache/managing/#cache-settings)
for listing current settings and definitions. Changes apply to new jobs.

## Overrides

Puppeteer's download-base environment variables override its configuration-file
values. Workflow and step environment variables can override the bases Avrea
sets. To use Puppeteer's default download configuration for a step, clear both:

```yaml
- run: npm rebuild puppeteer
  env:
    PUPPETEER_CHROME_DOWNLOAD_BASE_URL: ""
    PUPPETEER_CHROME_HEADLESS_SHELL_DOWNLOAD_BASE_URL: ""
```

See Puppeteer's [configuration guide](https://pptr.dev/guides/configuration),
[Chrome settings](https://pptr.dev/api/puppeteer.chromesettings), and
[headless-shell settings](https://pptr.dev/api/puppeteer.chromeheadlessshellsettings).