test: add firefox-esr example

README.md

@@ -25,32 +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.
 
-The [Chromium][Chromium] browser is available from [Debian][Debian-Chromium-Wiki] for both `amd64` and `arm64` architectures and the directory [examples/chromium](./examples/chromium/) demonstrates how the current version of Chromium for Debian can be added to Cypress Docker images.
-At this time, Chromium is not included in the `cypress/factory` build process (see [#1191](/~https://github.com/cypress-io/cypress-docker-images/issues/1191) for progress).
+- 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.
 
-<!-- chromium links -->
-[Chromium]: https://www.chromium.org/Home/
+<!-- 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/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>