Skip to content

docs: refresh included readme #1070

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

Merged
merged 1 commit into from
May 29, 2024
Merged

docs: refresh included readme #1070

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
77 changes: 44 additions & 33 deletions included/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@
This image should be enough to run Cypress tests headlessly or in the interactive mode with a single Docker command like this:

```shell
$ docker run -it -v $PWD:/e2e -w /e2e cypress/included:9.4.1
$ docker run -it -v $PWD:/e2e -w /e2e cypress/included:13.10.0
```

## Debug

If you want to see the [Cypress debug logs](https://on.cypress.io/debugging#Print-DEBUG-logs) during the run, pass environment variable `DEBUG`:

```shell
$ docker run -it -v $PWD:/e2e -w /e2e -e DEBUG=cypress:* cypress/included:9.4.1
```text
$ docker run -it -v $PWD:/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
Expand All @@ -24,67 +24,76 @@ $ docker run -it -v $PWD:/e2e -w /e2e -e DEBUG=cypress:* cypress/included:9.4.1

## Arguments

These images have its 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:
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:

```shell
$ docker run -it --entrypoint=cypress cypress/included:9.4.1 run --help
$ docker run -it --entrypoint=cypress cypress/included:13.10.0 run --help
```

To run a single spec using Chrome browser:

```shell
$ docker run -it --entrypoint=cypress cypress/included:9.4.1 run --spec cypress/integration/spec-a.js --browser chrome
$ docker run -it --entrypoint=cypress cypress/included:13.10.0 run --spec cypress/e2e/spec-a.cy.js --browser chrome
```

## Entry

These images have its 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
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

```shell
$ docker run -it --entrypoint=cypress cypress/included:9.4.1 info
```text
$ docker run -it --entrypoint=cypress cypress/included:13.10.0 info

DevTools listening on ws://127.0.0.1:41043/devtools/browser/7da6e086-a4eb-4408-acab-e22f3cb6c076
Displaying Cypress info...

Detected 2 browsers installed:
Detected 3 browsers installed:

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

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

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

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

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

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

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

Cypress Version: 9.4.1
System Platform: linux (Debian - 10.1)
System Memory: 2.09 GB free 285 MB
Cypress Version: 13.10.0 (stable)
System Platform: linux (Debian - 11.9)
System Memory: 5.16 GB free 4.09 GB
```

### Entry with arguments

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:

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

## Keep the container
Expand All @@ -93,8 +102,8 @@ Every time you run `docker run` you spawn a new container. That container then s

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:

```
$ docker run -it -v $PWD:/e2e -w /e2e --entrypoint=/bin/bash cypress/included:9.4.1
```text
$ docker run -it -v $PWD:/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
Expand All @@ -107,30 +116,32 @@ root@814ed01841fe:/e2e# cypress run

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

```shell
$ docker run -it -v $PWD:/e2e -w /e2e --entrypoint=cypress cypress/included:9.4.1 run --browser chrome
```text
$ docker run -it -v $PWD:/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

====================================================================================================

(Run Starting)

┌─────────────────────────────────
│ Cypress: 3.8.1
│ Browser: Chrome 77
│ Specs: 1 found (spec.js)
└─────────────────────────────────
┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 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} │
└────────────────────────────────────────────────────────────────────────────────────────────────┘

...
```

For more information, read [Run Cypress with a single Docker command](https://www.cypress.io/blog/2019/05/02/run-cypress-with-a-single-docker-command/) and [End-to-End Testing Web Apps: The Painless Way](https://mtlynch.io/painless-web-app-testing/)

## Default user

By default, the included images run as `root` user. You can switch the user to the second user in the image `node` or custom-mapped user, see [examples section](https://github.com/cypress-io/cypress-docker-images#examples). Starting with `cypress/included:3.8.1` we set permissions on the globally installed Cypress and set binary cache variable to allow other users read and execute access. Thus you will be able to run Cypress as non-root user by using `-u node`

```shell
$ docker run -it -v $PWD/src:/test -w /test -u node cypress/included:9.4.1
$ docker run -it -v $PWD/src:/test -w /test -u node cypress/included:13.10.0
```

## GitHub Action
Expand All @@ -146,7 +157,7 @@ If you want to run Cypress after a server has started, we suggest using [wait-on
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:9.4.1 # wait for the local site to respond
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'
```
Expand All @@ -156,5 +167,5 @@ docker run --rm # remove container after finish
If you want to simulate slow container, run the Docker container with `--cpus` parameter, for example, let's debug the browser detection problems when the CPU is (very) slow:

```shell
docker run -it -v $PWD:/e2e -w /e2e --cpus=0.02 -e DEBUG=cypress:launcher --entrypoint=cypress cypress/included:9.4.1 info
docker run -it -v $PWD:/e2e -w /e2e --cpus=0.02 -e DEBUG=cypress:launcher --entrypoint=cypress cypress/included:13.10.0 info
```