[pull] master from cypress-io:master

README.md

@@ -25,25 +25,46 @@ In the case of Windows environments, see [Docker Desktop for Windows](https://do
 
 Cypress Docker images [cypress/browsers](./browsers/) include browsers for the `Linux/amd64` platform. Availability is pending for the `Linux/arm64` platform.
 
-| Browser                    |   `Linux/amd64`    | `Linux/arm64`                                                                |
-| -------------------------- | :----------------: | :--------------------------------------------------------------------------- |
-| [Google Chrome][Chrome]    | :white_check_mark: | see [#1188](https://github.com/cypress-io/cypress-docker-images/issues/1188) |
-| [Mozilla Firefox][Firefox] | :white_check_mark: | see [#1190](https://github.com/cypress-io/cypress-docker-images/issues/1190) |
-| [Microsoft Edge][Edge]     | :white_check_mark: | see [#1189](https://github.com/cypress-io/cypress-docker-images/issues/1189) |
+| Browser                    |   `Linux/amd64`    | `Linux/arm64`                                                                                                                    |
+| -------------------------- | :----------------: | :------------------------------------------------------------------------------------------------------------------------------- |
+| [Google Chrome][Chrome]    | :white_check_mark: | see [#1188](https://github.com/cypress-io/cypress-docker-images/issues/1188)                                                     |
+| [Mozilla Firefox][Firefox] | :white_check_mark: | see [#1190](https://github.com/cypress-io/cypress-docker-images/issues/1190) and [examples/firefox-esr](./examples/firefox-esr/) |
+| [Microsoft Edge][Edge]     | :white_check_mark: | see [#1189](https://github.com/cypress-io/cypress-docker-images/issues/1189)                                                     |
 
 On POSIX-based systems, or with [Git for Windows](https://gitforwindows.org/) at a Git Bash prompt, execute `uname -m` to display your system's architecture. ([x86_64](https://en.wikipedia.org/wiki/X86-64) is equivalent to `amd64`.)
 
-<!-- browser links -->
+[cypress/included](./included/) images, which are built on top of [cypress/browsers](./browsers/), contain the same set of browsers.
+
+[Tags](#tag-selection) for [cypress/browsers](./browsers/) and [cypress/included](./included/) images show which versions of the browsers are loaded into the respective image. (Disregard the browser version tags for current `Linux/arm64` images however.)
+
+Building a custom image with [cypress/factory](./factory/) allows selection of individual browsers from the above list.
 
+<!-- browser links -->
 [Chrome]: https://developer.chrome.com/
 [Firefox]: https://www.mozilla.org/firefox
 [Edge]: https://developer.microsoft.com/microsoft-edge/
+[Chromium]: https://www.chromium.org/Home/
+[Firefox Channel Choice]: https://support.mozilla.org/en-US/kb/choosing-firefox-update-channel
 
-[cypress/included](./included/) images, which are built on top of [cypress/browsers](./browsers/), contain the same set of browsers.
+### Debian packages
 
-[Tags](#tag-selection) for [cypress/browsers](./browsers/) and [cypress/included](./included/) images show which versions of the browsers are loaded into the respective image. (Disregard the browser version tags for current `Linux/arm64` images however.)
+[Debian][Debian packages] provides two Cypress-compatible browsers as packages covering both `amd64` and `arm64` architectures.
+These can be used to complement the browsers that are configurable through the `cypress/factory` build process:
 
-Building a custom image with [cypress/factory](./factory/) allows selection of individual browsers from the above list.
+- See the directory [examples/chromium](./examples/chromium/) to add the current version of Chromium for Debian to Cypress Docker images.
+  The [Debian Chromium Wiki][Debian-Chromium-Wiki] describes the [Chromium][Chromium] browser distribution details.
+  Chromium is not currently included in the `cypress/factory` build process.
+  See [#1191](https://github.com/cypress-io/cypress-docker-images/issues/1191) for progress of this integration.
+
+- See the directory [examples/firefox-esr](./examples/firefox-esr/) to add Firefox ESR for Debian to Cypress Docker images.
+  The [Debian Firefox Wiki][Debian-Firefox-Wiki] describes the [Firefox][Firefox] browser distribution details from the [Extended Support Release][Firefox Channel Choice] channel.
+  This differs from the `cypress/factory` build process which uses Firefox `amd64` versions from the [Rapid Release][Firefox Channel Choice] channel.
+  See [#1190](https://github.com/cypress-io/cypress-docker-images/issues/1190) for availability of Firefox `arm64` [Rapid Release][Firefox Channel Choice] versions.
+
+<!-- Debian links -->
+[Debian packages]: https://www.debian.org/distrib/packages
+[Debian-Chromium-Wiki]: https://wiki.debian.org/Chromium
+[Debian-Firefox-Wiki]: https://wiki.debian.org/Firefox
 
 ## Tag Selection
 

examples/chromium/Dockerfile

@@ -0,0 +1,6 @@
+FROM cypress/base
+COPY . /opt/app
+WORKDIR /opt/app
+RUN apt-get update              # Update package index
+RUN apt-get install chromium -y # Install Chromium
+RUN npx cypress install         # Install Cypress binary

examples/chromium/README.md

@@ -0,0 +1,65 @@
+# examples/chromium
+
+This directory contains a simple example of a Cypress E2E test with one test spec `cypress/e2e/spec.cy.js` running using the Chromium browser.
+
+## Non-Docker demonstration
+
+Install Chromium on your host system.
+
+Use regular [Cypress CLI commands](https://docs.cypress.io/guides/guides/command-line) to run Cypress with Chromium:
+
+```shell
+cd examples/chromium
+npm ci
+npx cypress run --browser chromium
+npx cypress open --e2e --browser chromium
+```
+
+## Docker
+
+In the Docker examples below, the Chromium browser is installed from [Debian](https://www.debian.org/distrib/packages) distribution sources. See the [Chromium package](https://packages.debian.org/search?keywords=chromium) (`bookworm (stable)` section) for `amd64` and `arm64` versions respectively.
+
+### Docker interactive
+
+In this example we first run the unchanged image `cypress/base` as a container:
+
+```shell
+cd examples/chromium  # Use a pre-configured simple Cypress E2E project
+npm ci                # Install Cypress
+docker run -it --rm -v .:/e2e -w /e2e cypress/base  # Run image as container
+```
+
+At the `bash` prompt `:/e2e#`, we can then enter the following commands:
+
+```shell
+apt-get update                      # Update package index
+apt-get install chromium -y         # Install Chromium
+unset CI                            # Allows to see installation progress
+npx cypress install                 # Install Cypress binary into running Docker container
+npx cypress run --browser chromium  # Run Cypress test
+exit
+```
+
+### Docker build and run
+
+In this example we use a customized `Dockerfile` which bases a new image on `cypress/base`, copies the complete Cypress project into the image, including installed dependencies, then installs Chromium and the Cypress binary into the image.
+
+The file is [examples/chromium/Dockerfile](./Dockerfile) and it has the following contents:
+
+```dockerfile
+FROM cypress/base
+COPY . /opt/app
+WORKDIR /opt/app
+RUN apt-get update              # Update package index
+RUN apt-get install chromium -y # Install Chromium
+RUN npx cypress install         # Install Cypress binary
+```
+
+We build the new image, run the container from the image and execute the Cypress command `npx cypress run --browser chromium` to run the test using Chromium:
+
+```shell
+cd examples/chromium             # Use a pre-configured simple Cypress E2E project
+npm ci                           # Install all dependencies
+docker build . -t test-chromium  # Build a new image
+docker run -it --rm --entrypoint bash test-chromium -c "npx cypress run --browser chromium" # Run Cypress test using Chromium
+```

examples/chromium/cypress.config.js

@@ -0,0 +1,8 @@
+const { defineConfig } = require('cypress')
+
+module.exports = defineConfig({
+  fixturesFolder: false,
+  e2e: {
+    supportFile: false,
+  },
+})

examples/chromium/cypress/e2e/spec.cy.js

@@ -0,0 +1,6 @@
+describe('test local demo page', () => {
+  it('heading', () => {
+    cy.visit('index.html')
+    cy.contains('h2', 'Test')
+  })
+})

examples/chromium/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Test for Cypress Docker images</title>
+  </head>
+
+  <body>
+    <h1>Purpose</h1>
+    <p>This page is used for demonstrating Cypress Docker images.</p>
+    <h2>Test heading</h2>
+    <p>This is a test page</p>
+  </body>
+</html>