test: add chromium example

README.md

@@ -45,6 +45,13 @@ 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 [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).
+
+<!-- chromium links -->
+[Chromium]: https://www.chromium.org/Home/
+[Debian-Chromium-Wiki]: https://wiki.debian.org/Chromium
+
 ## 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/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>