Skip to content

Commit 9c86f23

Browse files
MikeMcC399MikeMcC399
authored
docs: extend included examples (#1246)
1 parent 39db851 commit 9c86f23

File tree

1 file changed

+87
-100
lines changed

1 file changed

+87
-100
lines changed

‎included/README.md‎

Lines changed: 87 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -13,186 +13,173 @@
1313

1414
[cypress/included](https://hub.docker.com/r/cypress/included/tags) images on [Cypress on Docker Hub](https://hub.docker.com/u/cypress) use image tags in the form:
1515

16-
- `<cypress version>`-node-`<node version>`-chrome-`<chrome version>`-ff-`<firefox version>`-edge-`<edge version>`-
16+
- cypress-`<cypress version>`-node-`<node version>`-chrome-`<chrome version>`-ff-`<firefox version>`-edge-`<edge version>`
1717
- `<cypress version>`<br>This is a short-form convenience tag, equivalent to the above full tag.
1818
- `latest`
1919

2020
for example:
2121

22-
- `cypress/included:cypress-13.11.0-node-20.14.0-chrome-125.0.6422.141-1-ff-126.0.1-edge-125.0.2535.85-1`
23-
- `cypress/included:13.11.0`
22+
- `cypress/included:cypress-13.15.1-node-22.11.0-chrome-130.0.6723.69-1-ff-132.0-edge-130.0.2849.56-1`
23+
- `cypress/included:13.15.1`
2424
- `cypress/included:latest`
2525

2626
To avoid unplanned breaking changes, specify a fixed `<cypress version>`, `<node version>` & `<browser version>` combination tag or use the short-form `<cypress version>` tag, not the `latest` tag. The `latest` tag is linked to the latest released `cypress/included` image and is updated without notice.
2727

2828
## ENTRYPOINT
2929

30-
When running a container from a `cypress/included` image, `cypress run` is executed, as defined by the [ENTRYPOINT](https://docs.docker.com/reference/dockerfile/#entrypoint) parameter of the image.
30+
`cypress/included` images have their Docker [ENTRYPOINT](https://docs.docker.com/reference/dockerfile/#entrypoint) set to `"cypress" "run"`.
3131

32-
## Usage
32+
To run a `cypress/included` image using `cypress run`, for instance to run all test specs in the default Electron browser, no additional [docker run](https://docs.docker.com/reference/cli/docker/container/run/) CLI options are needed.
3333

34-
This image should be enough to run Cypress tests headlessly or in the interactive mode with a single Docker command like this:
34+
To use [`cypress run` options](https://docs.cypress.io/app/references/command-line#cypress-run), such as `-b chrome`, use the [docker run](https://docs.docker.com/reference/cli/docker/container/run/) command with `--entrypoint cypress` to overwrite the default `ENTRYPOINT` of the `cypress/included` image.
35+
36+
To run `bash` commands interactively in the image, for instance to inspect files, directories or to run Cypress interactively, use the [docker run](https://docs.docker.com/reference/cli/docker/container/run/) command with `--entrypoint bash`.
37+
38+
See below for examples.
39+
40+
## Examples
41+
42+
> [!TIP]
43+
> Remove `cypress` from your project's `package.json` to avoid version mismatch between your project and the `cypress/included` Docker image.
44+
45+
The directory [examples/basic-mini](../examples/basic-mini/) in this repo provides an example project which includes a Cypress E2E test spec and has no Cypress version included in its [package.json](../examples/basic-mini/package.json).
46+
47+
### Docker interactive
48+
49+
In this example we first run the image `cypress/included` as a container, overriding the default command of `cypress run` using `--entrypoint bash` to enter the interactive `bash` shell.
50+
51+
```shell
52+
cd examples/basic-mini # Use a pre-configured simple Cypress E2E project
53+
docker run -it --rm -v .:/app -w /app --entrypoint bash cypress/included # Run image as container
54+
```
55+
56+
At the `bash` prompt `:/app#`, we can then enter the following commands:
3557

3658
```shell
37-
$ docker run -it -v .:/e2e -w /e2e cypress/included:13.10.0
59+
ls -al # Check the contents of our working directory
60+
npx cypress run -b chrome # Run Cypress test in Chrome
61+
exit
3862
```
3963

40-
## Debug
64+
### Docker default
4165

42-
If you want to see the [Cypress debug logs](https://on.cypress.io/troubleshooting#Print-DEBUG-logs) during the run, pass the environment variable setting `DEBUG=cypress:*`:
66+
In this example we let the Docker image handle running Cypress automatically through the pre-defined `cypress run` command. This runs Cypress with the default Electron browser:
4367

44-
```text
45-
$ docker run -it -v .:/e2e -w /e2e -e DEBUG=cypress:* cypress/included:13.10.0
46-
cypress:cli:cli cli starts with arguments ["/usr/local/bin/node","/usr/local/bin/cypress","run"] +0ms
47-
cypress:cli NODE_OPTIONS is not set +0ms
48-
cypress:cli:cli program parsing arguments +3ms
49-
...
68+
```shell
69+
cd examples/basic-mini # Use a pre-configured simple Cypress E2E project
70+
docker run -it --rm -v .:/app -w /app cypress/included # Run image as container and execute cypress run
5071
```
5172

52-
## Arguments
73+
### Browser
5374

54-
These images have their entry point set to `cypress run` without any additional arguments. You can specify additional Cypress CLI arguments after the image name. For example to print the Help menu for the `cypress run` command:
75+
To run `cypress/included` using one of the installed browsers (Chrome, Edge or Firefox), we change to `--entrypoint cypress` and add the command `run -b chrome`, for instance, to test against the Chrome browser:
5576

5677
```shell
57-
$ docker run -it --entrypoint=cypress cypress/included:13.10.0 run --help
78+
cd examples/basic-mini
79+
docker run -it --rm -v .:/app -w /app --entrypoint cypress cypress/included run -b chrome
5880
```
5981

60-
To run a single spec using Chrome browser:
82+
### Debug
83+
84+
To see [Cypress debug logs](https://on.cypress.io/troubleshooting#Print-DEBUG-logs) during the run, pass the environment variable setting with `-e DEBUG=cypress:*`:
6185

6286
```shell
63-
$ docker run -it -v .:/e2e -w /e2e --entrypoint=cypress cypress/included:13.10.0 run --spec cypress/e2e/spec.cy.js --browser chrome
87+
cd examples/basic-mini
88+
docker run -it --rm -v .:/app -w /app -e DEBUG=cypress:* cypress/included
6489
```
6590

66-
## Entry
91+
### Single test spec
6792

68-
These images have their entry point set to `cypress run`. If you want to run a different command, you need to set `--entrypoint=cypress` and specify arguments AFTER the image name. For example, to print the Cypress information using `cypress info` command
93+
To run a single test spec using the Chrome browser:
6994

70-
```text
71-
$ docker run -it --entrypoint=cypress cypress/included:13.10.0 info
95+
```shell
96+
cd examples/basic-mini
97+
docker run -it --rm -v .:/app -w /app --entrypoint cypress cypress/included run --spec cypress/e2e/spec.cy.js -b chrome
98+
```
99+
100+
### Info
72101

73-
DevTools listening on ws://127.0.0.1:41043/devtools/browser/7da6e086-a4eb-4408-acab-e22f3cb6c076
102+
To run [cypress info](https://docs.cypress.io/app/references/command-line#cypress-info) which prints information about Cypress and the current environment:
103+
104+
```shell
105+
cd examples/basic-mini
106+
docker run -it --rm --entrypoint cypress cypress/included info
107+
```
108+
109+
```text
110+
DevTools listening on ws://127.0.0.1:36243/devtools/browser/eb85524a-6459-41d6-b855-94c10cd2b242
74111
Displaying Cypress info...
75112
76113
Detected 3 browsers installed:
77114
78115
1. Chrome
79116
- Name: chrome
80117
- Channel: stable
81-
- Version: 125.0.6422.60
118+
- Version: 130.0.6723.69
82119
- Executable: google-chrome
83120
84121
2. Edge
85122
- Name: edge
86123
- Channel: stable
87-
- Version: 125.0.2535.51
124+
- Version: 130.0.2849.56
88125
- Executable: edge
89126
90127
3. Firefox
91128
- Name: firefox
92129
- Channel: stable
93-
- Version: 126.0
130+
- Version: 132.0
94131
- Executable: firefox
95132
96133
Note: to run these browsers, pass <name>:<channel> to the '--browser' field
97134
98135
Examples:
99136
- cypress run --browser firefox
100-
- cypress run --browser edge
137+
- cypress run --browser chrome
101138
102139
Learn More: https://on.cypress.io/launching-browsers
103140
104141
Proxy Settings: none detected
105142
Environment Variables:
106143
CYPRESS_CACHE_FOLDER: /root/.cache/Cypress
107-
CYPRESS_FACTORY_DEFAULT_NODE_VERSION: 20.13.1
144+
CYPRESS_FACTORY_DEFAULT_NODE_VERSION: 22.11.0
108145
109146
Application Data: /root/.config/cypress/cy/development
110147
Browser Profiles: /root/.config/cypress/cy/development/browsers
111148
Binary Caches: /root/.cache/Cypress
112149
113-
Cypress Version: 13.10.0 (stable)
114-
System Platform: linux (Debian - 11.9)
115-
System Memory: 5.16 GB free 4.09 GB
150+
Cypress Version: 13.15.1 (stable)
151+
System Platform: linux (Debian - 12.7)
152+
System Memory: 5.16 GB free 4.12 GB
116153
```
117154

118-
### Entry with arguments
155+
## User
119156

120-
If you want to provide Cypress command line arguments, specify the entry point and the arguments. For example to run tests with recording and parallel mode using custom build ID "abc123" we can use:
157+
By default, `cypress/included` images run as `root` user. You can switch to the non-root user `node` in the image or to a custom user.
121158

122-
```shell
123-
$ docker run -it -v .:/e2e -w /e2e --entrypoint=cypress cypress/included:13.10.0 run --record --parallel --ci-build-id abc123
124-
```
125-
126-
## Keep the container
127-
128-
Every time you run `docker run` you spawn a new container. That container then stops after the tests finish, but there is nothing Cypress can do about it - it is the Docker command `docker run ...` that controls this behavior.
129-
130-
If you are running a lot of tests again and again, you might start the container once using Bash as the entrypoint, instead of the default `cypress` command. Then you can execute the `cypress run` or any other commands, while still in the same container:
131-
132-
```text
133-
$ docker run -it -v .:/e2e -w /e2e --entrypoint=/bin/bash cypress/included:13.10.0
134-
# we are inside the container
135-
# let's run the tests
136-
root@814ed01841fe:/e2e# cypress run
137-
....
138-
# run the tests again
139-
root@814ed01841fe:/e2e# cypress run
140-
```
141-
142-
## Browser
143-
144-
If you want to use a different browser (assuming it is installed in the container) use:
145-
146-
```text
147-
$ docker run -it -v .:/e2e -w /e2e --entrypoint=cypress cypress/included:13.10.0 run --browser chrome
148-
149-
DevTools listening on ws://127.0.0.1:45315/devtools/browser/0c510bb9-b365-49e7-8a99-67f3c69e1ab9
159+
- [examples/included-as-non-root](../examples/included-as-non-root) describes how to run tests as non-root user `node` using a `cypress/included` image
150160

151-
====================================================================================================
161+
## Continuous Integration
152162

153-
(Run Starting)
163+
`cypress/included` images are a convenient tool to run Cypress tests from the command line with all dependencies pre-installed. With their corresponding fixed version of Cypress, they are not primarily intended for use in Continuous Integration (CI) workflows.
154164

155-
┌────────────────────────────────────────────────────────────────────────────────────────────────┐
156-
│ Cypress: 13.10.0 │
157-
│ Browser: Chrome 125 (headless) │
158-
│ Node Version: v20.13.1 (/usr/local/bin/node) │
159-
│ Specs: 1 found (spec.cy.js) │
160-
│ Searched: cypress**/*.cy.{js,jsx,ts,tsx} │
161-
└────────────────────────────────────────────────────────────────────────────────────────────────┘
165+
[cypress/base](../base/README.md) and [cypress/browsers](../browsers/README.md) images, which are independent of the Cypress version used, are generally better suited for CI use. The required version of Cypress is then dynamically installed into the workflow with one of the [package managers supported](https://docs.cypress.io/app/get-started/install-cypress#Install) by Cypress.
162166

163-
...
164-
```
167+
If you do use `cypress/included` in CI, note the special handling recommended in the following sections:
165168

166-
## Default user
169+
### GitHub Actions
167170

168-
By default, `cypress/included` images run as `root` user. You can switch to the non-root user `node` in the image or to a custom-mapped user, see the [Alternate users](#alternate-users) section below.
171+
The example workflow [.github/workflows/example-cypress-github-action.yml](../.github/workflows/example-cypress-github-action.yml), job `docker-included`, demonstrates how to use a `cypress/included` image in a GitHub Actions workflow.
169172

170-
## GitHub Action
173+
If you use a `cypress/included` image in a [GitHub Actions](https://docs.github.com/en/actions) workflow that executes the [Cypress JavaScript GitHub Action `cypress-io/github-action`](https://github.com/cypress-io/github-action), it is recommended to set the environment variable `CYPRESS_INSTALL_BINARY=0` to [skip Cypress binary installation](https://docs.cypress.io/app/references/advanced-installation#Skipping-installation). This avoids unnecessary caching attempts for the Cypress binary. `cypress/included` images already include the cached Cypress binary and additional caching attempts with a non-root user can lead to non-fatal error messages. The example workflow, mentioned above, shows how to set the environment variable `CYPRESS_INSTALL_BINARY`.
171174

172-
You can quickly run your tests in GitHub Actions using these images, see [GitHub Action example](https://github.com/cypress-io/github-action#docker-image) repository.
175+
### GitLab Pipelines
173176

174-
## Wait-on
177+
If you use a `cypress/included` image in a [GitLab CI/CD pipeline](https://docs.gitlab.com/ee/ci/pipelines/) you need to [override the default entrypoint](https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#override-the-entrypoint-of-an-image) with an empty value, otherwise the pipeline will fail.
175178

176-
If you want to run Cypress after a server has started, we suggest using [wait-on](https://github.com/jeffbski/wait-on#readme) utility. To use it from the `cypress/included` image, you need to disable the default entrypoint and set a new command like this:
179+
For example:
177180

178-
```shell
179-
# execute the Cypress container once
180-
docker run --rm # remove container after finish
181-
-v ./e2e:/e2e # map current folder to "e2e" folder
182-
--workdir=/e2e --entrypoint="" # remove default entrypoint command
183-
cypress/included:13.10.0 # wait for the local site to respond
184-
# then run Cypress tests
185-
/bin/bash -c 'npx wait-on http://127.0.0.1:3000 && cypress run'
181+
```yml
182+
image:
183+
name: cypress/included
184+
entrypoint: [""]
186185
```
187-
188-
## Restrict CPU
189-
190-
If you want to simulate a slow container, run the Docker container with the `--cpus` parameter, for example, let's debug possible browser detection problems when the CPU is slow:
191-
192-
```shell
193-
docker run -it --cpus=0.2 -e DEBUG=cypress:launcher:* --entrypoint=cypress cypress/included:13.10.0 info
194-
```
195-
196-
## Alternate users
197-
198-
- [examples/included-as-non-root](../examples/included-as-non-root) describes how to run tests as non-root user `node` using a `cypress/included` image

0 commit comments

Comments
 (0)