From 2d86e2ab779cba64f6a905abca8eb7e448bfb9b9 Mon Sep 17 00:00:00 2001
From: Mike McCready <66998419+MikeMcC399@users.noreply.github.com>
Date: Tue, 11 Jun 2024 18:24:06 +0200
Subject: [PATCH] docs: add cypress/browsers examples

---
 browsers/README.md                 | 45 +++++++++++++++++++++++++++++-
 examples/basic/Dockerfile.browsers |  4 +++
 2 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 examples/basic/Dockerfile.browsers

diff --git a/browsers/README.md b/browsers/README.md
index 13937c1eaa..ebc94a3b53 100644
--- a/browsers/README.md
+++ b/browsers/README.md
@@ -16,4 +16,47 @@ for example:
 - `cypress/browsers:node-20.14.0-chrome-125.0.6422.141-1-ff-126.0.1-edge-125.0.2535.85-1`
 - `cypress/browsers:latest`
 
- To avoid unplanned breaking changes, specify a fixed `<node version>` & `<browser version>` combination tag, not the `latest` tag.  The `latest` tag is linked to the latest released `cypress/browsers` image and is updated without notice.
+To avoid unplanned breaking changes, specify a fixed `<node version>` & `<browser version>` combination tag, not the `latest` tag.  The `latest` tag is linked to the latest released `cypress/browsers` image and is updated without notice.
+
+## CMD
+
+When running a container from a `cypress/browsers` image, `bash` is executed, as defined by the [CMD](https://docs.docker.com/reference/dockerfile/#cmd) parameter of the image.
+
+### Docker interactive
+
+In this example we first run the unchanged image `cypress/browsers` as a container:
+
+```shell
+cd examples/basic         # Use a pre-configured simple Cypress E2E project
+npm ci                    # Install Cypress
+docker run -it --rm -v .:/e2e -w /e2e cypress/browsers  # Run image as container
+```
+
+At the `bash` prompt `:/e2e#`, we can then enter the following commands:
+
+```shell
+npx cypress install       # Install Cypress binary into running Docker container
+npx cypress run -b chrome # Run Cypress test in Chrome
+```
+
+### Docker build and run
+
+In this example we use a customized `Dockerfile` which bases a new image on `cypress/browsers`, copies the complete Cypress project into the image, including installed dependencies, then installs the Cypress binary.
+
+The file is [examples/basic/Dockerfile.browsers](../examples/basic/Dockerfile.browsers) and it has the following contents:
+
+```dockerfile
+FROM cypress/browsers
+COPY . /opt/app
+WORKDIR /opt/app
+RUN npx cypress install # Install Cypress binary into image
+```
+
+We build the new image, run the container from the image and execute the Cypress command `npx cypress run -b chrome` to run the test using the Chrome browser:
+
+```shell
+cd examples/basic         # Use a pre-configured simple Cypress E2E project
+npm ci                    # Install Cypress
+docker build . -f Dockerfile.browsers -t test-browsers  # Build a new image
+docker run -it --rm --entrypoint bash test-browsers -c "npx cypress run -b chrome" # Run Cypress test in container using Chrome
+```
diff --git a/examples/basic/Dockerfile.browsers b/examples/basic/Dockerfile.browsers
new file mode 100644
index 0000000000..8bd4c604fc
--- /dev/null
+++ b/examples/basic/Dockerfile.browsers
@@ -0,0 +1,4 @@
+FROM cypress/browsers
+COPY . /opt/app
+WORKDIR /opt/app
+RUN npx cypress install # Install Cypress binary into image