test: add firefox-esr example

README.md

@@ -25,11 +25,11 @@ 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`.)
 
@@ -45,6 +45,12 @@ On POSIX-based systems, or with [Git for Windows](https://gitforwindows.org/) at
 
 Building a custom image with [cypress/factory](./factory/) allows selection of individual browsers from the above list.
 
+The [Firefox][Firefox] browser from the [Extended Support Release][Firefox ESR] channel is available from [Debian][Debian-Firefox-Wiki] for both `amd64` and `arm64` architectures and the directory [examples/firefox-esr](./examples/firefox-esr/) demonstrates how Firefox ESR for Debian can be added to Cypress Docker images.
+
+<!-- firefox links -->
+[Debian-Firefox-Wiki]: https://wiki.debian.org/Firefox
+[Firefox ESR]: https://support.mozilla.org/en-US/kb/choosing-firefox-update-channel
+
 ## Tag Selection
 
 If no tag is specified, for example `cypress/included`, then the tag `latest` is used by default: `cypress/included:latest`. It is however recommended to use a specific image tag to avoid breaking changes when new images are released, especially when they include new major versions of Node.js or Cypress.

examples/firefox-esr/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 firefox-esr -y # Install Firefox ESR
+RUN npx cypress install            # Install Cypress binary

examples/firefox-esr/README.md

@@ -0,0 +1,67 @@
+# examples/firefox-esr
+
+This directory contains a simple example of a Cypress E2E test with one test spec `cypress/e2e/spec.cy.js` running using the [Mozilla Firefox](https://www.mozilla.org/firefox) browser from the ESR (Extended Support Release) channel.
+
+[Choosing a Firefox update channel](https://support.mozilla.org/en-US/kb/choosing-firefox-update-channel) explains the Firefox "Extended Support Release (ESR)".
+
+## Non-Docker demonstration
+
+Install Firefox ESR on your host system.
+
+Use regular [Cypress CLI commands](https://docs.cypress.io/guides/guides/command-line) to run Cypress with Firefox (ESR):
+
+```shell
+cd examples/firefox-esr
+npm ci
+npx cypress run --browser firefox
+npx cypress open --e2e --browser firefox
+```
+
+## Docker
+
+In the Docker examples below, the Firefox ESR browser is installed from [Debian](https://www.debian.org/distrib/packages) distribution sources. See the [firefox-esr package](https://packages.debian.org/search?keywords=firefox-esr) (`bookworm (stable)` section) covering `amd64 arm64 armhf i386 mips64el ppc64el s390x` processor architectures.
+
+### Docker interactive
+
+In this example we first run the unchanged image `cypress/base` as a container:
+
+```shell
+cd examples/firefox-esr  # 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 firefox-esr -y     # Install Firefox ESR
+unset CI                           # Allows to see installation progress
+npx cypress install                # Install Cypress binary into running Docker container
+npx cypress run --browser firefox  # 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 Firefox ESR and the Cypress binary into the image.
+
+The file is [examples/firefox-esr/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 firefox-esr -y # Install Firefox ESR
+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 firefox` to run the test using Firefox ESR:
+
+```shell
+cd examples/firefox-esr             # Use a pre-configured simple Cypress E2E project
+npm ci                              # Install all dependencies
+docker build . -t test-firefox-esr  # Build a new image
+docker run -it --rm --entrypoint bash test-firefox-esr -c "npx cypress run --browser firefox" # Run Cypress test using Firefox ESR
+```

examples/firefox-esr/cypress.config.js

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

examples/firefox-esr/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/firefox-esr/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>