Skip to content

Commit

Permalink
cleanup docker doc (#168)
Browse files Browse the repository at this point in the history
* cleanup docker doc

* swap out all example repo gifs for static images

* cleanup CI doc, remove outdated content, tighten up some content, update running in CI gif

* clarify on what you'll learn and what cypress run actually does
  • Loading branch information
bahmutov authored and brian-mann committed Oct 25, 2017
1 parent 23513e9 commit 39dfab3
Show file tree
Hide file tree
Showing 12 changed files with 25 additions and 79 deletions.
2 changes: 1 addition & 1 deletion source/examples/applications/kitchen-sink.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ This is an example app is used to showcase every command available in Cypress.
- {% url "`cy.route()`" route %} network requests, {% url "`cy.wait()`" wait %} on responses, and stub response data using {% url "`cy.fixture()`" fixture %}.
- Inspect and manipulate cookies and localStorage.

![kitchensink running](/img/examples/kitchen-sink-tests-running.gif)
![kitchensink running](/img/examples/public-project-kitchen-sink.png)

## Stack

Expand Down
2 changes: 1 addition & 1 deletion source/examples/applications/phonecat.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ This tests the {% url "original Angular Phonecat example app" https://github.com
- Test redirect behavior of application using {% url "`.hash()`" hash %}.
- Test loading behavior of app.

![phonecat-angular-tutorial-app-tested-in-cypress 2d78065e](/img/examples/phonecat-angular-app.jpg)
![phonecat-angular-tutorial-app-tested-in-cypress 2d78065e](/img/examples/public-project-phone-cat.jpg)


## Stack
Expand Down
2 changes: 1 addition & 1 deletion source/examples/applications/pie-chopper.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ This is a single page application with a decent amount of features. The tests in
- Check checkboxes using {% url `cy.check()` check %}
- Stub responses from our backend using {% url `cy.route()` route %}

![piechopper-gif](/img/examples/piechopper-tests-running.gif)
![piechopper-gif](/img/examples/public-project-piechopper.png)

## Stack

Expand Down
2 changes: 1 addition & 1 deletion source/examples/applications/todo-mvc.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ This repo compares {% url "Cypress Tests" https://github.com/cypress-io/cypress-
- Create a custom `cy.createTodo()` command to run multiple cy commands.
- Click and double click elements using {% url "`cy.click()`" click %} and {% url "`cy.dblclick()`" dblclick %}.

![todomvc-gif](/img/examples/todomvc-tests-running.gif)
![todomvc-gif](/img/examples/public-project-todomvc.png)

## Stack

Expand Down
9 changes: 5 additions & 4 deletions source/guides/guides/command-line.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,10 @@ comments: false
{% note info %}
# {% fa fa-graduation-cap %} What You'll Learn

- How to run Cypress headlessly from the command line
- How to record your tests running from the command line
- How to launch other browsers from the command line
- How to run Cypress from the command line
- How to run headlessly
- How to launch other browsers
- How to record your tests
{% endnote %}

# Installation
Expand All @@ -33,7 +34,7 @@ Or just add cypress commands to the `scripts` field in your `package.json` file.

## `cypress run`

Run Cypress headlessly. By default will run all tests headlessly in the `Electron` browser.
Runs Cypress to completion. By default will run all tests headlessly in the `Electron` browser.

***Run tests***

Expand Down
87 changes: 16 additions & 71 deletions source/guides/guides/continuous-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ title: Continuous Integration
comments: false
---

Running Cypress tests in Continuous Integration is as easy as running tests locally. You generally only need to do two things:
Running Cypress in Continuous Integration is the same as running it locally. You generally only need to do two things:

1. **Include Cypress package**
1. **Install Cypress**

```shell
npm install cypress --save-dev
Expand All @@ -17,11 +17,11 @@ Running Cypress tests in Continuous Integration is as easy as running tests loca
cypress run
```

That's it! This will go out and {% url 'install Cypress' installing-cypress %}, and then run all your tests.
That's it!

For a comprehensive list of all the options you can pass to {% url '`cypress run`' command-line#cypress-run %}, {% url 'refer to the command line documentation' command-line %}.
For more examples please read the {% url 'Command Line' command-line#cypress-run %} documentation.

{% img /img/guides/travis-ci-logs-running-cypress.gif "travis-logs" %}
{% img /img/guides/running-in-ci.gif "Running in Circle CI" %}

# What's Supported?

Expand All @@ -32,11 +32,13 @@ Cypress should run on **all** CI providers. We currently have seen Cypress worki
- {% url "CircleCI" https://circleci.com %}
- {% url "CodeShip" https://codeship.com/ %}
- {% url "GitLab" https://gitlab.com %}
- {% url "BuildKite" https://buildkite.com %}
- {% url "AppVeyor" https://appveyor.com %}
- {% url "Docker" https://www.docker.com/ %}

# Setting Up CI

Depending on which CI provider you use, you may need a config file. You'll want to refer to your CI provider's documentation to know where to add the commands to install and run Cypress. For more example config files check out any of our {% url "example apps" unit-testing-recipe %}.
Depending on which CI provider you use, you may need a config file. You'll want to refer to your CI provider's documentation to know where to add the commands to install and run Cypress. For more example config files check out any of our {% url "example apps" kitchen-sink %}.

## Travis

Expand All @@ -59,12 +61,18 @@ test:

## Docker

We have {% url 'created' https://github.com/cypress-io/docker %} an official {% url 'cypress/base' 'https://hub.docker.com/r/cypress/base/' %} container with all of the required dependencies installed. Just add Cypress and go! As an experiment we have also created a complete {% url 'cypress/internal:cy' 'https://hub.docker.com/r/cypress/internal/tags/' %} image with pre-installed Cypress; just call {% url '`cypress run`' command-line#cypress-run %}.
We have {% url 'created' https://github.com/cypress-io/docker %} an official {% url 'cypress/base' 'https://hub.docker.com/r/cypress/base/' %} container with all of the required dependencies installed. Just add Cypress and go! We are also adding images with browsers pre-installed under {% url 'cypress/browsers' 'https://hub.docker.com/r/cypress/browsers/' %} name. A typical Dockerfile would look like this:

If you don't use this image you must install all of the {% url 'linux dependencies' continuous-integration#Dependencies %}. See {% issue 165 'this issue' %} for more information.
```text
FROM cypress/base
RUN npm install
RUN $(npm bin)/cypress run
```

***Docker CI examples***

Here are a few CI example repositories using our Docker images

* {% url "GitLab" https://gitlab.com/cypress-io/cypress-example-docker-gitlab %}
* {% url "Codeship" https://github.com/cypress-io/cypress-example-docker-codeship %}
* {% url "CircleCI" https://github.com/cypress-io/cypress-example-docker-circle %}
Expand All @@ -78,8 +86,6 @@ If you are not using one of the above CI providers then make sure your system ha
apt-get install xvfb libgtk2.0-0 libnotify-dev libgconf-2-4 libnss3 libxss1 libasound
```

If you run {% url '`cypress run`' command-line#cypress-run %} and see no output {% url 'see this section for troubleshooting this known issue' continuous-integration#Troubleshooting %}.

# Recording Tests in CI

Cypress can record your tests running and make them available in our {% url 'Dashboard' https://on.cypress.io/dashboard %}.
Expand Down Expand Up @@ -167,69 +173,8 @@ cy.request({
Refer to the dedicated {% url 'Environment Variables Guide' environment-variables %} for more examples.
{% endnote %}

# Optimizing CI with Caching

Most CI providers allow caching of directories or dependencies between builds. This allows you to cache the state of Cypress and make the builds run faster.

## Travis CI

***.travis.yml***

```yaml
cache:
directories:
- /home/travis/.cypress/Cypress
```

## CircleCI

***circle.yml***

```yaml
## make sure you set the correct node version based on what you've installed!
dependencies:
cache_directories:
- /home/ubuntu/nvm/versions/node/v6.2.2/bin/cypress
- /home/ubuntu/nvm/versions/node/v6.2.2/lib/node_modules/cypress-cli
- /home/ubuntu/.cypress/Cypress
```

# Known Issues

## CircleCI

You need to select their {% url "`Ubuntu 12.04` image" https://circleci.com/docs/build-image-precise/ %}. The `Ubuntu 14.04` image does not have all of the required dependencies installed by default. You can likely install them yourself. {% issue 315 'There is an open issue for this here.' %}

![Ubuntu build environment in circle](/img/guides/ubuntu-build-environment-in-circle-ci.png)

## Jenkins

You need to install all of the {% url 'linux dependencies' continuous-integration#Dependencies %}.

## Docker

If you are running long runs on Docker, you need to set the `ipc` to `host` mode. {% issue 350 'This issue' %} describes exactly what to do.

# Troubleshooting

## No Output

***Symptom***

After executing {% url '`cypress run`' command-line#cypress-run %} you don't see any output. In other words: nothing happens.

***Problem***

You are missing {% url 'a dependency' continuous-integration#Dependencies %} above. *Please install all of the dependencies.*

The reason you're not seeing any output is a longstanding issue with Cypress which {% issue 317 'there is an open issue for' %}. We are working on improving this experience!

***Seeing Errors***

Although running {% url '`cypress run`' command-line#cypress-run %} will yield no output - you can see the actual dependency failure by invoking the Cypress binary directly.

***Invoke the Cypress binary directly***

```shell
/home/YOUR_USER/.cypress/Cypress/Cypress
```
Binary file removed source/img/examples/phonecat-angular-app.jpg
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/img/examples/public-project-phone-cat.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/img/examples/public-project-todomvc.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/img/guides/running-in-ci.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 39dfab3

Please sign in to comment.