Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: extend included examples #1246

Merged
merged 1 commit into from
Nov 4, 2024
Merged

docs: extend included examples #1246

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 87 additions & 100 deletions included/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,186 +13,173 @@

[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:

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

for example:

- `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`
- `cypress/included:13.11.0`
- `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`
- `cypress/included:13.15.1`
- `cypress/included:latest`

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.

## ENTRYPOINT

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.
`cypress/included` images have their Docker [ENTRYPOINT](https://docs.docker.com/reference/dockerfile/#entrypoint) set to `"cypress" "run"`.

## Usage
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.

This image should be enough to run Cypress tests headlessly or in the interactive mode with a single Docker command like this:
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.

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`.

See below for examples.

## Examples

> [!TIP]
> Remove `cypress` from your project's `package.json` to avoid version mismatch between your project and the `cypress/included` Docker image.

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).

### Docker interactive

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.

```shell
cd examples/basic-mini # Use a pre-configured simple Cypress E2E project
docker run -it --rm -v .:/app -w /app --entrypoint bash cypress/included # Run image as container
```

At the `bash` prompt `:/app#`, we can then enter the following commands:

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

## Debug
### Docker default

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:*`:
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:

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

## Arguments
### Browser

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:
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:

```shell
$ docker run -it --entrypoint=cypress cypress/included:13.10.0 run --help
cd examples/basic-mini
docker run -it --rm -v .:/app -w /app --entrypoint cypress cypress/included run -b chrome
```

To run a single spec using Chrome browser:
### Debug

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:*`:

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

## Entry
### Single test spec

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
To run a single test spec using the Chrome browser:

```text
$ docker run -it --entrypoint=cypress cypress/included:13.10.0 info
```shell
cd examples/basic-mini
docker run -it --rm -v .:/app -w /app --entrypoint cypress cypress/included run --spec cypress/e2e/spec.cy.js -b chrome
```

### Info

DevTools listening on ws://127.0.0.1:41043/devtools/browser/7da6e086-a4eb-4408-acab-e22f3cb6c076
To run [cypress info](https://docs.cypress.io/app/references/command-line#cypress-info) which prints information about Cypress and the current environment:

```shell
cd examples/basic-mini
docker run -it --rm --entrypoint cypress cypress/included info
```

```text
DevTools listening on ws://127.0.0.1:36243/devtools/browser/eb85524a-6459-41d6-b855-94c10cd2b242
Displaying Cypress info...

Detected 3 browsers installed:

1. Chrome
- Name: chrome
- Channel: stable
- Version: 125.0.6422.60
- Version: 130.0.6723.69
- Executable: google-chrome

2. Edge
- Name: edge
- Channel: stable
- Version: 125.0.2535.51
- Version: 130.0.2849.56
- Executable: edge

3. Firefox
- Name: firefox
- Channel: stable
- Version: 126.0
- Version: 132.0
- Executable: firefox

Note: to run these browsers, pass <name>:<channel> to the '--browser' field

Examples:
- cypress run --browser firefox
- cypress run --browser edge
- cypress run --browser chrome

Learn More: https://on.cypress.io/launching-browsers

Proxy Settings: none detected
Environment Variables:
CYPRESS_CACHE_FOLDER: /root/.cache/Cypress
CYPRESS_FACTORY_DEFAULT_NODE_VERSION: 20.13.1
CYPRESS_FACTORY_DEFAULT_NODE_VERSION: 22.11.0

Application Data: /root/.config/cypress/cy/development
Browser Profiles: /root/.config/cypress/cy/development/browsers
Binary Caches: /root/.cache/Cypress

Cypress Version: 13.10.0 (stable)
System Platform: linux (Debian - 11.9)
System Memory: 5.16 GB free 4.09 GB
Cypress Version: 13.15.1 (stable)
System Platform: linux (Debian - 12.7)
System Memory: 5.16 GB free 4.12 GB
```

### Entry with arguments
## User

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:
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.

```shell
$ docker run -it -v .:/e2e -w /e2e --entrypoint=cypress cypress/included:13.10.0 run --record --parallel --ci-build-id abc123
```

## Keep the container

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.

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:

```text
$ docker run -it -v .:/e2e -w /e2e --entrypoint=/bin/bash cypress/included:13.10.0
# we are inside the container
# let's run the tests
root@814ed01841fe:/e2e# cypress run
....
# run the tests again
root@814ed01841fe:/e2e# cypress run
```

## Browser

If you want to use a different browser (assuming it is installed in the container) use:

```text
$ docker run -it -v .:/e2e -w /e2e --entrypoint=cypress cypress/included:13.10.0 run --browser chrome

DevTools listening on ws://127.0.0.1:45315/devtools/browser/0c510bb9-b365-49e7-8a99-67f3c69e1ab9
- [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

====================================================================================================
## Continuous Integration

(Run Starting)
`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.

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Cypress: 13.10.0 │
│ Browser: Chrome 125 (headless) │
│ Node Version: v20.13.1 (/usr/local/bin/node) │
│ Specs: 1 found (spec.cy.js) │
│ Searched: cypress**/*.cy.{js,jsx,ts,tsx} │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
[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.

...
```
If you do use `cypress/included` in CI, note the special handling recommended in the following sections:

## Default user
### GitHub Actions

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.
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.

## GitHub Action
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`.

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.
### GitLab Pipelines

## Wait-on
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.

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:
For example:

```shell
# execute the Cypress container once
docker run --rm # remove container after finish
-v ./e2e:/e2e # map current folder to "e2e" folder
--workdir=/e2e --entrypoint="" # remove default entrypoint command
cypress/included:13.10.0 # wait for the local site to respond
# then run Cypress tests
/bin/bash -c 'npx wait-on http://127.0.0.1:3000 && cypress run'
```yml
image:
name: cypress/included
entrypoint: [""]
```

## Restrict CPU

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:

```shell
docker run -it --cpus=0.2 -e DEBUG=cypress:launcher:* --entrypoint=cypress cypress/included:13.10.0 info
```

## Alternate users

- [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