From 8033fbf819ee38c92ac20416b62ef4dce51f6fa6 Mon Sep 17 00:00:00 2001 From: Brian Mann Date: Sat, 2 Dec 2017 18:51:42 -0500 Subject: [PATCH] Issue 995 (#996) * better explain contributing to the driver - update npm tasks to reflect newest conventions * better explain contributing to the desktop-gui - update npm tasks to reflect newest conventions * synchronize content changes * capitalize all package readme's for consistency * better explain contributing to the runner, synchronize content changes * better explain contributing to the server * synchronize content * synchronize content * synchronize content * synchronize content * synchronize content * synchronize content * better contribution guidelines by redirecting users to package specific readme's * synchronize content * fix various content mistakes * simplify contributing * removed dead files * bump zunder * lock zunder to 5.1.0 --- .eslintignore | 1 + CONTRIBUTING.md | 87 +++++++----------------- circle.yml | 16 ++--- packages/desktop-gui/.eslintrc | 5 -- packages/desktop-gui/.travis.yml | 15 ---- packages/desktop-gui/README.md | 75 ++++++++++++++++++++ packages/desktop-gui/circle.yml | 16 ----- packages/desktop-gui/package.json | 5 +- packages/desktop-gui/readme.md | 26 ------- packages/driver/{readme.md => README.md} | 63 +++++++++++++---- packages/driver/package.json | 6 +- packages/electron/.release.json | 8 --- packages/electron/README.md | 22 ++++-- packages/electron/circle.yml | 3 - packages/example/.release.json | 8 --- packages/example/.travis.yml | 17 ----- packages/example/README.md | 80 +--------------------- packages/example/circle.yml | 16 ----- packages/extension/.release.json | 8 --- packages/extension/README.md | 31 +++++---- packages/extension/circle.yml | 3 - packages/https-proxy/.release.json | 8 --- packages/https-proxy/README.md | 18 ++--- packages/https-proxy/circle.yml | 7 -- packages/https-proxy/package.json | 3 +- packages/launcher/.release.json | 8 --- packages/launcher/README.md | 18 +++-- packages/reporter/.eslintrc | 5 -- packages/reporter/.release.json | 8 --- packages/reporter/README.md | 33 +++++---- packages/reporter/circle.yml | 3 - packages/reporter/package.json | 2 +- packages/runner/.eslintrc | 5 -- packages/runner/.release.json | 8 --- packages/runner/README.md | 36 ++++++---- packages/runner/circle.yml | 3 - packages/runner/package.json | 2 +- packages/server/.eslintignore | 1 - packages/server/.eslintrc | 8 --- packages/server/README.md | 63 +++++++++++++++++ packages/server/readme.md | 17 ----- packages/socket/.release.json | 8 --- packages/socket/README.md | 20 ++---- packages/socket/circle.yml | 5 -- 44 files changed, 332 insertions(+), 468 deletions(-) delete mode 100644 packages/desktop-gui/.eslintrc delete mode 100644 packages/desktop-gui/.travis.yml create mode 100644 packages/desktop-gui/README.md delete mode 100644 packages/desktop-gui/circle.yml delete mode 100644 packages/desktop-gui/readme.md rename packages/driver/{readme.md => README.md} (70%) delete mode 100644 packages/electron/.release.json delete mode 100644 packages/electron/circle.yml delete mode 100644 packages/example/.release.json delete mode 100644 packages/example/.travis.yml delete mode 100644 packages/example/circle.yml delete mode 100644 packages/extension/.release.json delete mode 100644 packages/extension/circle.yml delete mode 100644 packages/https-proxy/.release.json delete mode 100644 packages/https-proxy/circle.yml delete mode 100644 packages/launcher/.release.json delete mode 100644 packages/reporter/.eslintrc delete mode 100644 packages/reporter/.release.json delete mode 100644 packages/reporter/circle.yml delete mode 100644 packages/runner/.eslintrc delete mode 100644 packages/runner/.release.json delete mode 100644 packages/runner/circle.yml delete mode 100644 packages/server/.eslintignore delete mode 100644 packages/server/.eslintrc create mode 100644 packages/server/README.md delete mode 100644 packages/server/readme.md delete mode 100644 packages/socket/.release.json delete mode 100644 packages/socket/circle.yml diff --git a/.eslintignore b/.eslintignore index 5c30aa14b2..1e654ae4c9 100644 --- a/.eslintignore +++ b/.eslintignore @@ -2,4 +2,5 @@ __snapshots__ packages/server/lib/scaffold/plugins/index.js packages/server/lib/scaffold/support/index.js packages/server/lib/scaffold/support/commands.js +packages/server/test/fixtures packages/example/cypress diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 836e03bbff..ca6fae508e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,9 +28,7 @@ Thanks for taking the time to contribute! :smile: - [Getting Started](#getting-started) - [Coding Style](#coding-style) - [Tests](#tests) - - [Working in a specific package](#packages) - - [Desktop-Gui](#desktop-gui) - - [Driver](#driver) + - [Packages](#packages) - [Writing Documentation](#writing-documentation) - [Committing Code](#committing-code) - [Pull Requests](#pull-requests) @@ -153,21 +151,21 @@ Here is a list of the core packages in this repository with a short description, Folder Name | Purpose ----------- | ------- -[coffee]() | A centralized version of CoffeeScript used for other packages. -[desktop-gui]() | The front-end code for the Cypress Desktop GUI. -[driver]() | The code that is used to drive the behavior of the API commands. -[electron]() | The Cypress implementation of Electron. -[example]() | Our example kitchen-sink application. -[extension]() | The Cypress Chrome browser extension -[https-proxy]() | This does https proxy for handling http certs and traffic. -[launcher]() | Finds and launches browsers installed on your system. -[reporter]() | The reporter shows the running results of the tests (The Command Log UI). -[root]() | Dummy package pointing at the root of the repository. -[runner]() | The runner is the minimal "chrome" around the user's application under test. -[server]() | The <3 of Cypress. This orchestrates everything. The entire backend. -[socket]() | A wrapper around socket.io to provide common libraries. -[static]() | Serves static assets used in the Cypress GUI. -[ts]() | A centralized version of typescript. +[coffee](./packages/coffee) | A centralized version of CoffeeScript used for other packages. +[desktop-gui](./packages/desktop-gui) | The front-end code for the Cypress Desktop GUI. +[driver](./packages/driver) | The code that is used to drive the behavior of the API commands. +[electron](./packages/electron) | The Cypress implementation of Electron. +[example](./packages/example) | Our example kitchen-sink application. +[extension](./packages/extension) | The Cypress Chrome browser extension +[https-proxy](./packages/https-proxy) | This does https proxy for handling http certs and traffic. +[launcher](./packages/launcher) | Finds and launches browsers installed on your system. +[reporter](./packages/reporter) | The reporter shows the running results of the tests (The Command Log UI). +[root](./packages/root) | Dummy package pointing at the root of the repository. +[runner](./packages/runner) | The runner is the minimal "chrome" around the user's application under test. +[server](./packages/server) | The <3 of Cypress. This orchestrates everything. The backend node process. +[socket](./packages/socket) | A wrapper around socket.io to provide common libraries. +[static](./packages/static) | Serves static assets used in the Cypress GUI. +[ts](./packages/ts) | A centralized version of typescript. We try to tag all issues with a `pkg/` tag describing the appropriate package the work is required in. For example, the [`pkg/driver`](https://github.com/cypress-io/cypress/labels/pkg%2Fdriver) label is tagged on issues that require work in the `driver` package. @@ -206,11 +204,11 @@ Task | Purpose `build` | Build the package `build-prod` | Build all assets for production (if makes sense) `start` | Run a server for serving files +`watch` | Watch source files and build development assets when they are saved. This may also run a server for serving files and run tests related to a saved file. `clean` | Remove any assets created by `build-dev` or `build-prod` `clean-deps` | Remove any dependencies installed (usually by `npm`) `test` | Runs all tests once `test-watch` | Run all tests in watch mode -`watch` | Watch source files and build development assets when they are saved. This may also run a server for serving files and run tests related to a saved file. Not every package requires or makes use of every script, so it is simply omitted from that package's `package.json` and not run. @@ -272,20 +270,13 @@ We use [eslint](https://eslint.org/) to lint all JavaScript code and follow rule ### Tests - For most packages, there are unit, integration and e2e tests, which can be triggered by `npm run test-unit`, `npm run test-integration` and `npm run test-e2e` respectively. +For most packages there are typically unit and some integration tests. Our true e2e tests are in `packages/server`, which test the full stack all together. -The best source of truth in figuring out how to run tests for each package is our [`circle.yml`](.circle.yml) file found in the root `cypress` directory. The tasks defined in our [`circle.yml`](.circle.yml) are all run before anything is deployed. +Please refer to each packages' `README.md` which documents how to run tests. It is not feasible to try to run all of the tests together. We run our entire test fleet across over a dozen containers in CI. -Since it is generally best to do single runs of tests serially instead of in parallel, this repo has some convenience scripts to run all the tests for all the packages sequentially: - -```bash -npm run test ## same as 'npm run all test -- --serial' -npm run test-unit ## same as 'npm run all test-unit -- --serial' -npm run test-integration ## same as 'npm run all test-integration -- --serial' -npm run test-e2e ## same as 'npm run all test-e2e -- --serial' -``` +If you're curious how we manage all of these tests in CI check out our [`circle.yml`](circle.yml) file found in the root `cypress` directory. #### Docker @@ -320,41 +311,13 @@ cd packages/desktop-gui npm rebuild node-sass ``` -### Working in a specific package +### Packages -#### Desktop-Gui +Generally when making contributions, you are typically making it to a small number of packages. Most of your local development work will be inside a single package at a time. -##### Developing - -Currently, if you want to work on the code around logging in, viewing runs, and setting up new projects to record, this requires connecting to a locally running API server. - -Our API server is only accessible to cypress employees at the moment. If you want to work with the code, we recommend working within the Cypress tests for the Desktop-Gui. There are lots of tests mocking our API server around logging in, seeing runs, and setting up projects. - -#### Driver - -##### Developing - -It should be noted that for developing in the `driver`, you need to watch the files using one of the following methods: - -- In the `cypress` root directory run `npm run watch`: This will run the watch task for all packages that have one. -- In the `cypress/packages/runner` directory run `npm run watch`: This will run the watch task for the runner, which bundles the driver. - -##### Testing - -###### From the Cypress Test Runner: - -- In the `cypress` root directory, run `npm install` & `npm start`. -- When the Cypress Test Runner opens, manually add the directory `cypress/packages/driver/test`. -- In the `cypress/packages/driver` directory, run `npm start`. -- Click into the `test` directory from the Cypress Test Runner. -- Select any test file you want to run. - -###### From the terminal: - -- In the `cypress` directory: run `npm install`. -- In the `cypress/packages/driver` directory, run `npm start` & `npm run test-integration`. -- The Cypress Test Runner should spawn and run through each test file individually. +Each package documents how to best work with it, so simple consult the `README.md` of each package. +They will outline development and test procedures. When in doubt just look at the `scripts` of each `package.json` file. Everything we do at Cypress is contained there. ## Writing Documentation @@ -381,6 +344,8 @@ The repository is setup with two main (protected) branches. This repository is exhaustively tested by [CircleCI](https://circleci.com/gh/cypress-io/cypress). Additionally we test the code by running it against various other example projects. See CI badges and links at the top of this document. +To run local tests, consult the `README.md` of each package. + ## Deployment We will try to review and merge pull requests quickly. After merging we diff --git a/circle.yml b/circle.yml index 02d3382445..f26d40cf12 100644 --- a/circle.yml +++ b/circle.yml @@ -291,7 +291,7 @@ jobs: command: $(npm bin)/wait-on http://localhost:3500 working_directory: packages/driver - run: - command: npm run test-integration -- --parallel 5 --index 0 + command: npm run cypress:run -- --parallel 5 --index 0 working_directory: packages/driver - store_test_results: path: /tmp/cypress-monorepo @@ -311,7 +311,7 @@ jobs: command: $(npm bin)/wait-on http://localhost:3500 working_directory: packages/driver - run: - command: npm run test-integration -- --parallel 5 --index 1 + command: npm run cypress:run -- --parallel 5 --index 1 working_directory: packages/driver - store_test_results: path: /tmp/cypress-monorepo @@ -331,7 +331,7 @@ jobs: command: $(npm bin)/wait-on http://localhost:3500 working_directory: packages/driver - run: - command: npm run test-integration -- --parallel 5 --index 2 + command: npm run cypress:run -- --parallel 5 --index 2 working_directory: packages/driver - store_test_results: path: /tmp/cypress-monorepo @@ -351,7 +351,7 @@ jobs: command: $(npm bin)/wait-on http://localhost:3500 working_directory: packages/driver - run: - command: npm run test-integration -- --parallel 5 --index 3 + command: npm run cypress:run -- --parallel 5 --index 3 working_directory: packages/driver - store_test_results: path: /tmp/cypress-monorepo @@ -371,7 +371,7 @@ jobs: command: $(npm bin)/wait-on http://localhost:3500 working_directory: packages/driver - run: - command: npm run test-integration -- --parallel 5 --index 4 + command: npm run cypress:run -- --parallel 5 --index 4 working_directory: packages/driver - store_test_results: path: /tmp/cypress-monorepo @@ -387,7 +387,7 @@ jobs: command: npm run build-prod working_directory: packages/desktop-gui - run: - command: npm run test-integration -- --parallel 3 --index 0 + command: npm run cypress:run -- --parallel 3 --index 0 working_directory: packages/desktop-gui - store_test_results: path: /tmp/cypress-monorepo @@ -403,7 +403,7 @@ jobs: command: npm run build-prod working_directory: packages/desktop-gui - run: - command: npm run test-integration -- --parallel 3 --index 1 + command: npm run cypress:run -- --parallel 3 --index 1 working_directory: packages/desktop-gui - store_test_results: path: /tmp/cypress-monorepo @@ -419,7 +419,7 @@ jobs: command: npm run build-prod working_directory: packages/desktop-gui - run: - command: npm run test-integration -- --parallel 3 --index 2 + command: npm run cypress:run -- --parallel 3 --index 2 working_directory: packages/desktop-gui - store_test_results: path: /tmp/cypress-monorepo diff --git a/packages/desktop-gui/.eslintrc b/packages/desktop-gui/.eslintrc deleted file mode 100644 index b87bdb775b..0000000000 --- a/packages/desktop-gui/.eslintrc +++ /dev/null @@ -1,5 +0,0 @@ -{ - "extends": [ - "plugin:cypress-dev/general" - ] -} diff --git a/packages/desktop-gui/.travis.yml b/packages/desktop-gui/.travis.yml deleted file mode 100644 index b20f303d0a..0000000000 --- a/packages/desktop-gui/.travis.yml +++ /dev/null @@ -1,15 +0,0 @@ -language: node_js - -node_js: - - 6.1.0 - -install: - - npm install - - npm install -g cypress-cli - -before_script: - - npm run build-prod - - npm run server -- --silent & - -script: - - cypress run --record diff --git a/packages/desktop-gui/README.md b/packages/desktop-gui/README.md new file mode 100644 index 0000000000..ee892b4d88 --- /dev/null +++ b/packages/desktop-gui/README.md @@ -0,0 +1,75 @@ +# Desktop GUI + +The Desktop GUI is the react application that is rendered by Electron. This acts as the visual user interface you see when running: `cypress open`. + +The Desktop GUI has the following responsibilities: + +- Allowing users to login through GitHub. +- Allowing users to add projects to be tested in Cypress. +- Displaying existing projects and allowing the removal of projects. +- Initializing the server to run on a specific project. +- Allowing users to choose a specific browser to run tests within. +- Displaying the resolved configuration of a running project. +- Displaying the list of tests of a running project. +- Initializing the run of a specific test file or all tests chosen by the user. +- Notifying users of updates to Cypress and initializing update process. + +## Install + +The Desktop GUI's dependencies can be installed with: + +```bash +cd packages/desktop-gui +npm install +``` + +## Development + +### Watching + +This watches and compiles all changes as you make them. + +- Runs `*.js` and `*.jsx` through babel and bundles with browserify into `dist` +- Compiles `*.scss` files into `dist` + +```bash +npm run watch +``` + +### One Time Build + +#### For development + +```bash +npm run build +``` + +#### For production + +```bash +npm run build-prod +``` + +## Testing + +This project is tested with Cypress itself. It acts exactly like any other Cypress project. + +### Developing + +If you're developing on the Desktop GUI, you'll want to run in the normal Cypress GUI mode, like you would when you're writing tests for your own Cypress projects. + +```bash +## run in cypress GUI mode +npm run cypress:open +``` + +### Running + +You can also run all of the Desktop GUI's tests locally. We don't really recommend this because it takes a long time, and we have this process optimized by load balancing the tests across multiple workers in CI. + +It's usually easier to run the tests in the GUI, commit, and then see if anything broke elsewhere. + +```bash +## run all the tests +npm run cypress:run +``` diff --git a/packages/desktop-gui/circle.yml b/packages/desktop-gui/circle.yml deleted file mode 100644 index 94768d4813..0000000000 --- a/packages/desktop-gui/circle.yml +++ /dev/null @@ -1,16 +0,0 @@ -machine: - node: - version: 6.5.0 - -dependencies: - override: - - npm install - - npm install -g cypress-cli - -test: - pre: - - npm run build-prod - - npm run server: - background: true - override: - - cypress run --record diff --git a/packages/desktop-gui/package.json b/packages/desktop-gui/package.json index 9528388e77..63e78cdda5 100644 --- a/packages/desktop-gui/package.json +++ b/packages/desktop-gui/package.json @@ -11,7 +11,8 @@ "clean": "zunder clean", "clean-deps": "rm -rf node_modules", "lint": "$(bin-up eslint) --fix lib/*.js src/*.js* src/**/*.js*", - "test-integration": "node ../../scripts/run-cypress-tests.js" + "cypress:open": "node ../../scripts/start.js", + "cypress:run": "node ../../scripts/run-cypress-tests.js" }, "files": [ "dist", @@ -42,6 +43,6 @@ "react-bootstrap-modal": "3.0.1", "react-dom": "^15.6.1", "react-loader": "^2.4.0", - "zunder": "4.1.1" + "zunder": "5.1.0" } } diff --git a/packages/desktop-gui/readme.md b/packages/desktop-gui/readme.md deleted file mode 100644 index cc372e5e64..0000000000 --- a/packages/desktop-gui/readme.md +++ /dev/null @@ -1,26 +0,0 @@ -# packages/desktop-gui - -The desktop GUI is the desktop application installed to the user's OS. - -The desktop GUI has the following responsibilities: - -- Allowing users to login through GitHub. -- Allowing users to add projects to be tested in Cypress. -- Displaying existing projects and allowing the removal of projects. -- Initializing the server to run on a specific project. -- Allowing users to choose a specific browser to run tests within. -- Displaying the resolved configuration of a running project. -- Displaying the list of tests of a running project. -- Initializing the run of a specific test file or all tests chosen by the user. -- Notifying users of updates to Cypress and initializing update process. - -## Install - -Root install is preferred (see `CONTRIBUTING.md`), but if you must - -* `npm install` -* `npm run build` - -## Testing - -This project does not have its own tests, but instead is tested by `packages/server` diff --git a/packages/driver/readme.md b/packages/driver/README.md similarity index 70% rename from packages/driver/readme.md rename to packages/driver/README.md index 11347a4765..4cfd0594b5 100644 --- a/packages/driver/readme.md +++ b/packages/driver/README.md @@ -1,36 +1,69 @@ -# Cypress Driver +# Driver -> JavaScript library that is loaded inside the browser that helps execute the tests +This is the core JavaScript library that is loaded inside the browser that is responsible for executing Cypress commands and managing the test runtime. ## Install -Root install is preferred (see `CONTRIBUTING.md`), but if you must +The driver's dependencies can be installed with: -* `npm install` -* `npm run build` +```bash +cd packages/driver +npm install +``` + +## Building + +The driver is actually consumed by the [`runner`](../runner) like any other npm module. To develop the driver and see changes reflected you need to run the `watch` task inside of the runner. + +```bash +cd packages/runner +npm run watch +``` + +Read the runner's [`README.md`](../runner/README.md) for more information. ## Testing -This project is not tested, the existing test commands are obsolete and will be removed -in the future; all tests have been moved to other packages. +This project is tested with Cypress itself. It acts exactly like any other Cypress project (really we're not kidding!). -## Debugging - -To see logs of what the driver is doing from command line: +The driver uses a node server to test all of its edge cases, so first start that. ```bash -DEBUG=cypress:driver npm start - -DEBUG=cypress:driver npm run build +## boot the driver's server +npm start ``` +### Developing + +If you're developing on the driver, you'll want to run in the normal Cypress GUI mode, like you would when you're writing tests for your own Cypress projects. + +```bash +## run in cypress GUI mode +npm run cypress:open +``` + +### Running + +You can also run all of the driver's tests locally. We don't really recommend this because it takes a long time, and we have this process optimized by load balancing the tests across multiple workers in CI. + +It's usually easier to run the tests in the GUI, commit, and then see if anything broke elsewhere. + +```bash +## run all the tests +npm run cypress:run +``` + +## Debugging + In the browser ```js localStorage.debug = "cypress:driver" ``` -## Catalog of Events + diff --git a/packages/driver/package.json b/packages/driver/package.json index b124eeeeb9..c266c83e94 100644 --- a/packages/driver/package.json +++ b/packages/driver/package.json @@ -6,10 +6,8 @@ "browser": "src/main", "scripts": { "start": "coffee test/support/server.coffee", - "test-unit": "mocha", - "test-unit-watch": "./test/support/watch", - "test-unit-debug": "node --inspect --debug-brk ./node_modules/.bin/_mocha", - "test-integration": "node ../../scripts/run-cypress-tests.js --browser chrome --dir test", + "cypress:open": "node ../../scripts/start.js --project ./test", + "cypress:run": "node ../../scripts/run-cypress-tests.js --browser chrome --dir test", "clean-deps": "rm -rf node_modules" }, "files": [ diff --git a/packages/electron/.release.json b/packages/electron/.release.json deleted file mode 100644 index ebded8e6e4..0000000000 --- a/packages/electron/.release.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "commitMessage": "release %s", - "tagAnnotation": "release %s", - "github": { - "release": false, - "releaseName": "release %s" - } -} diff --git a/packages/electron/README.md b/packages/electron/README.md index f25afc7cd0..bd85a81294 100644 --- a/packages/electron/README.md +++ b/packages/electron/README.md @@ -1,14 +1,22 @@ -# Cypress Core Electron +# Electron -This is a shared lib for Cypress which manages installing + building the Cypress Electron application. +This is the lib responsible for installing + building Electron. This enables us to develop with the Electron shell that will match how the final compiled Cypress binary looks 1:1. -It is a simple wrapper that `symlinks` while in development. +It does this by using `symlinks` while in development. ## Install -Root install is preferred (see `CONTRIBUTING.md`), but if you must +The Desktop GUI's dependencies can be installed with: -* `npm install` -* `npm run build` +```bash +cd packages/desktop-gui +npm install +``` -Note: `npm run build` just installs Electron binary for this platform +## Building + +```bash +npm run build +``` + +Note: `npm run build` just installs Electron binary for your OS specific platform diff --git a/packages/electron/circle.yml b/packages/electron/circle.yml deleted file mode 100644 index 01a764d917..0000000000 --- a/packages/electron/circle.yml +++ /dev/null @@ -1,3 +0,0 @@ -machine: - node: - version: 6.5.0 diff --git a/packages/example/.release.json b/packages/example/.release.json deleted file mode 100644 index ebded8e6e4..0000000000 --- a/packages/example/.release.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "commitMessage": "release %s", - "tagAnnotation": "release %s", - "github": { - "release": false, - "releaseName": "release %s" - } -} diff --git a/packages/example/.travis.yml b/packages/example/.travis.yml deleted file mode 100644 index 5cb05248db..0000000000 --- a/packages/example/.travis.yml +++ /dev/null @@ -1,17 +0,0 @@ -language: node_js - -node_js: - - 5.10 - -install: - - npm install - - ## install the Cypress CLI Tools - ## which gives us access to the - ## `cypress` command used below - - npm install -g cypress-cli - -script: - - npm run build - - - cypress run --record diff --git a/packages/example/README.md b/packages/example/README.md index 686b050027..788ce57e7f 100644 --- a/packages/example/README.md +++ b/packages/example/README.md @@ -1,4 +1,4 @@ -## Cypress Example [![Circle CI](https://circleci.com/gh/cypress-io/cypress-core-example.svg?style=svg)](https://circleci.com/gh/cypress-io/cypress-core-example) [![Travis CI Build Status](https://travis-ci.org/cypress-io/cypress-core-example.svg?branch=master)](https://travis-ci.org/cypress-io/cypress-core-example) +## Example This repo contains the source code for pushing out [https://example.cypress.io](https://example.cypress.io). @@ -36,81 +36,3 @@ npm run deploy ```bash npm run release ``` - -## Changelog - -#### 0.8.0 -- new traversal methods - -#### 0.7.1 -- fix flaky test - -#### 0.7.0 -- bump kitchensink dep, spies, stubs, clocks, cy.readfile fixes - -#### 0.6.3 -- fix missing var - -#### 0.6.2 -- bump kitchen sink default config values - -#### 0.6.1 -- prevent file server from caching - -#### 0.6.0 -- new cy commands - -#### 0.5.5 -- do not postinstall - -#### 0.5.4 -- renamed commandTimeout -> defaultCommandTimeout - -#### 0.5.3 -- updated example spec - -#### 0.5.2 -- removed committed screenshots - -#### 0.5.1 -- bump kitchen sink to 0.4.1 - -#### 0.5.0 -- added cy.screenshot - -#### 0.4.0 -- added cy.exec() example from kitchen-sink dep - -#### 0.3.3 -- fixes clearing 3rd party cookies after cy.visit - -#### 0.3.2 -- bump kitchen sink dep - -#### 0.3.1 -- fix failed push - -#### 0.3.0 -- new cypress cookie commands - -#### 0.2.5 -- bumped cypress-example-kitchensink - -#### 0.2.4 -- updated node version to 5.10.0 -- updated deps - -#### 0.2.3 -- renamed visitTimeout -> pageLoadTimeout - -#### 0.2.2 -- build in ci first - -#### 0.2.1 -- bugfix do not preinstall or postinstall - -#### 0.2.0 -- public interface for accessing path to example_spec.js - -#### 0.1.0 -- initial release diff --git a/packages/example/circle.yml b/packages/example/circle.yml deleted file mode 100644 index 9b06b3dadf..0000000000 --- a/packages/example/circle.yml +++ /dev/null @@ -1,16 +0,0 @@ -machine: - node: - version: 6.5.0 - -dependencies: - post: - ## install the Cypress CLI Tools - ## which gives us access to the - ## `cypress` command used below - - npm install -g cypress-cli - - - npm run build - -test: - override: - - cypress run --record diff --git a/packages/extension/.release.json b/packages/extension/.release.json deleted file mode 100644 index ebded8e6e4..0000000000 --- a/packages/extension/.release.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "commitMessage": "release %s", - "tagAnnotation": "release %s", - "github": { - "release": false, - "releaseName": "release %s" - } -} diff --git a/packages/extension/README.md b/packages/extension/README.md index a5ba6e9b98..2b18c6bca5 100644 --- a/packages/extension/README.md +++ b/packages/extension/README.md @@ -1,37 +1,42 @@ -# Cypress packages/extension +# Extension -> Chrome Extension for loading our testing code into the browser +This is the Chrome Extension responsible for automating Chrome ## Install -Root install is preferred (see `CONTRIBUTING.md`), but if you must - -* `npm install` -* `npm run build -## Developing - -### Building +The extension's dependencies can be installed with: ```bash -npm run build-prod +cd packages/extension +npm install ``` +## Developing + ### Watching ```bash -npm run watch-dev +npm run watch ``` -### Testing +### One Time Building + +```bash +npm run build +``` + +## Testing ```bash npm run test ``` +## Debugging + 1. Open Chrome 2. Go into Extensions 3. Check **Developer Mode** 4. Click **Load unpacked extension...** -5. Choose **cypress-core-extension/dist** directory +5. Choose **packages/extension/dist** directory 6. Click **background page** to debug `background.js` 7. Click **Reload (⌘R)** to pull in changes to `manifest.json` diff --git a/packages/extension/circle.yml b/packages/extension/circle.yml deleted file mode 100644 index 01a764d917..0000000000 --- a/packages/extension/circle.yml +++ /dev/null @@ -1,3 +0,0 @@ -machine: - node: - version: 6.5.0 diff --git a/packages/https-proxy/.release.json b/packages/https-proxy/.release.json deleted file mode 100644 index ebded8e6e4..0000000000 --- a/packages/https-proxy/.release.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "commitMessage": "release %s", - "tagAnnotation": "release %s", - "github": { - "release": false, - "releaseName": "release %s" - } -} diff --git a/packages/https-proxy/README.md b/packages/https-proxy/README.md index cf1a8aa1e9..6604d660a4 100644 --- a/packages/https-proxy/README.md +++ b/packages/https-proxy/README.md @@ -1,17 +1,19 @@ -# Cypress Core Extension +# HTTPS Proxy -> Intercepts requests from the website under test +This package is responsible for acting as a CA authority and generating dynamic certificates on the fly for outbound HTTPS connections. + +This package enables Cypress to inspect and modify bytes coming in and out of the browser. ## Install -Root install is preferred (see `CONTRIBUTING.md`), but if you must +The proxy's dependencies can be installed with: -* `npm install` -* `npm run build` +```bash +cd packages/https-proxy +npm install +``` -## Developing - -**Testing** +## Testing ```bash npm test diff --git a/packages/https-proxy/circle.yml b/packages/https-proxy/circle.yml deleted file mode 100644 index 36c8abd913..0000000000 --- a/packages/https-proxy/circle.yml +++ /dev/null @@ -1,7 +0,0 @@ -machine: - node: - version: 6.5.0 - -test: - override: - - npm run test-ci diff --git a/packages/https-proxy/package.json b/packages/https-proxy/package.json index 88568ac301..cd5829c2a2 100644 --- a/packages/https-proxy/package.json +++ b/packages/https-proxy/package.json @@ -8,8 +8,7 @@ "clean-deps": "rm -rf node_modules", "test": "cross-env NODE_ENV=test bin-up mocha --reporter mocha-multi-reporters --reporter-options configFile=../../mocha-reporter-config.json", "test-watch": "cross-env NODE_ENV=test bin-up mocha --watch", - "https": "node https.js", - "release": "releaser" + "https": "node https.js" }, "files": [ "lib" diff --git a/packages/launcher/.release.json b/packages/launcher/.release.json deleted file mode 100644 index ebded8e6e4..0000000000 --- a/packages/launcher/.release.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "commitMessage": "release %s", - "tagAnnotation": "release %s", - "github": { - "release": false, - "releaseName": "release %s" - } -} diff --git a/packages/launcher/README.md b/packages/launcher/README.md index 0afa3c1a4d..05a5bbb734 100644 --- a/packages/launcher/README.md +++ b/packages/launcher/README.md @@ -1,13 +1,15 @@ -# Cypress Core Launcher +# Launcher -> Finds and launches browsers on each platform +This package finds and launches browsers for each operating system. ## Install -Root install is preferred (see `CONTRIBUTING.md`), but if you must +The launcher's dependencies can be installed with: -* `npm install` -* `npm run build` +```bash +cd packages/launcher +npm install +``` ## Development @@ -25,3 +27,9 @@ DEBUG=cypress:launcher npm test ## Demo To see browsers detected on your machine, just run `node index.js` + +## Testing + +```bash +npm run test +``` diff --git a/packages/reporter/.eslintrc b/packages/reporter/.eslintrc deleted file mode 100644 index b87bdb775b..0000000000 --- a/packages/reporter/.eslintrc +++ /dev/null @@ -1,5 +0,0 @@ -{ - "extends": [ - "plugin:cypress-dev/general" - ] -} diff --git a/packages/reporter/.release.json b/packages/reporter/.release.json deleted file mode 100644 index ebded8e6e4..0000000000 --- a/packages/reporter/.release.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "commitMessage": "release %s", - "tagAnnotation": "release %s", - "github": { - "release": false, - "releaseName": "release %s" - } -} diff --git a/packages/reporter/README.md b/packages/reporter/README.md index b079618bca..fa2b8ec587 100644 --- a/packages/reporter/README.md +++ b/packages/reporter/README.md @@ -1,4 +1,4 @@ -# cypress/reporter +# Reporter ![Reporter](https://cloud.githubusercontent.com/assets/1157043/17947006/bffba412-6a18-11e6-86ee-af7e9c9d614e.png) @@ -19,13 +19,26 @@ The reporter shows the running results of the tests. It includes the following: ## Install -Root install is preferred (see `CONTRIBUTING.md`), but if you must +The reporters's dependencies can be installed with: -* `npm install` +```bash +cd packages/reporter +npm install +``` ## Development -### Building +### Watching + +- Runs `*.js` and `*.jsx` through babel and bundles with browserify into single `dist/reporter.js` +- Runs associated unit test of file saved and outputs to terminal +- Compiles `*.scss` files to single `dist/reporter.css` + +```bash +npm run watch +``` + +### One Time Building #### For development @@ -39,17 +52,7 @@ npm run build-dev npm run build-prod ``` -### Watching - -- Runs `*.js` and `*.jsx` through babel and bundles with browserify into single `dist/reporter.js` -- Runs associated unit test of file saved and outputs to terminal -- Compiles `*.scss` files to single `dist/reporter.css` - -```bash -npm run watch -``` - -### Testing +## Testing ```bash npm test diff --git a/packages/reporter/circle.yml b/packages/reporter/circle.yml deleted file mode 100644 index 01a764d917..0000000000 --- a/packages/reporter/circle.yml +++ /dev/null @@ -1,3 +0,0 @@ -machine: - node: - version: 6.5.0 diff --git a/packages/reporter/package.json b/packages/reporter/package.json index d476dd3bee..f931bf0a98 100644 --- a/packages/reporter/package.json +++ b/packages/reporter/package.json @@ -59,6 +59,6 @@ "rebuild-node-sass": "^1.1.0", "sinon": "^1.17.4", "sinon-chai": "^2.8.0", - "zunder": "^4.1.1" + "zunder": "5.1.0" } } diff --git a/packages/runner/.eslintrc b/packages/runner/.eslintrc deleted file mode 100644 index b87bdb775b..0000000000 --- a/packages/runner/.eslintrc +++ /dev/null @@ -1,5 +0,0 @@ -{ - "extends": [ - "plugin:cypress-dev/general" - ] -} diff --git a/packages/runner/.release.json b/packages/runner/.release.json deleted file mode 100644 index ebded8e6e4..0000000000 --- a/packages/runner/.release.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "commitMessage": "release %s", - "tagAnnotation": "release %s", - "github": { - "release": false, - "releaseName": "release %s" - } -} diff --git a/packages/runner/README.md b/packages/runner/README.md index 89edb1fa03..1c1155dd30 100644 --- a/packages/runner/README.md +++ b/packages/runner/README.md @@ -1,4 +1,4 @@ -# Cypress Core Runner +# Runner ![Runner](https://cloud.githubusercontent.com/assets/1157043/17947042/e9352ae2-6a18-11e6-85af-3670c7cfba03.png) @@ -10,13 +10,29 @@ The runner is the minimal "chrome" around the user's app and has the following r ## Install -Root install is preferred (see `CONTRIBUTING.md`), but if you must +The runner's dependencies can be installed with: -* `npm install` +```bash +cd packages/runner +npm install +``` ## Development -### Building +### Watching + +This watches and compiles all changes as you make them. + +- Runs `*.js` and `*.jsx` through babel and bundles with browserify into single `dist/cypress_runner.js` +- Runs associated unit test of file saved and outputs to terminal +- Compiles `*.scss` files to single `dist/cypress_runner.css` +- Additionally it compiles both the [`reporter`](../reporter) and [`driver`](../driver) + +```bash +npm run watch +``` + +### One Time Build #### For development @@ -30,17 +46,7 @@ npm run build npm run build-prod ``` -### Watching - -- Runs `*.js` and `*.jsx` through babel and bundles with browserify into single `dist/runner.js` -- Runs associated unit test of file saved and outputs to terminal -- Compiles `*.scss` files to single `dist/runner.css` - -```bash -npm run watch -``` - -### Testing +## Testing ```bash npm test diff --git a/packages/runner/circle.yml b/packages/runner/circle.yml deleted file mode 100644 index 01a764d917..0000000000 --- a/packages/runner/circle.yml +++ /dev/null @@ -1,3 +0,0 @@ -machine: - node: - version: 6.5.0 diff --git a/packages/runner/package.json b/packages/runner/package.json index 489e5ab4f9..10db9076a8 100644 --- a/packages/runner/package.json +++ b/packages/runner/package.json @@ -40,6 +40,6 @@ "rebuild-node-sass": "^1.1.0", "sinon": "^1.17.5", "sinon-chai": "^2.8.0", - "zunder": "^5.1.0" + "zunder": "5.1.0" } } diff --git a/packages/server/.eslintignore b/packages/server/.eslintignore deleted file mode 100644 index a843dc44a1..0000000000 --- a/packages/server/.eslintignore +++ /dev/null @@ -1 +0,0 @@ -test/fixtures diff --git a/packages/server/.eslintrc b/packages/server/.eslintrc deleted file mode 100644 index b32d48eecb..0000000000 --- a/packages/server/.eslintrc +++ /dev/null @@ -1,8 +0,0 @@ -{ - "extends": [ - "plugin:cypress-dev/general" - ], - "env": { - "node": true - } -} diff --git a/packages/server/README.md b/packages/server/README.md new file mode 100644 index 0000000000..f8d4eb9845 --- /dev/null +++ b/packages/server/README.md @@ -0,0 +1,63 @@ +# Server + +This is the heart of the Cypress application. All of this code represents the node process running behind the browser application. This node process is responsible for: + +- Proxying every byte coming in and out of the browser +- Performing and normalizing automation tasks for each browser +- Coordinating and synchronizing state with the Desktop GUI and the Driver +- Performing node specific tasks on behalf of the Driver +- Instantiating and orchestrating nearly every other layer and package +- Spinning up various static file and http servers +- Communicating with our external API's +- Recording videos of run +- Managing mocha reporters +- Managing 3rd party plugins + +The Driver and the Server are the two most complex areas of the Cypress. + +## Install + +The server's dependencies can be installed with: + +```bash +cd packages/server +npm install +``` + +## Development + +To run Cypress: + +```bash +npm start ## boots the entire Cypress application +``` + +Since the server controls nearly every aspect of Cypress, after making changes you'll need to manually restart Cypress. + +Since this is slow, it's better to drive your development with tests. + +## Testing + +* `npm run test-unit` executes unit tests in `test/unit` +* `npm run test-integration` executes integration tests in `test/integration` +* `npm run test-e2e` executes the large (slow) end to end tests in `test/e2e` + +Each of these tasks can run in "watch" mode by appending this word to the task: + +```bash +npm run test-unit-watch +``` + +Because of the large number of dependencies of the server, it's much more performant to run a single individual test. + +```bash +## runs only this one test file +npm run test ./test/unit/api_spec.coffee +``` + +You can also run in `watch` mode + +```bash +## runs and watches only this one test file +npm run test-watch ./test/unit/api_spec.coffee +``` diff --git a/packages/server/readme.md b/packages/server/readme.md deleted file mode 100644 index 419baafb6f..0000000000 --- a/packages/server/readme.md +++ /dev/null @@ -1,17 +0,0 @@ -# packages/server - -> The ❤️ of Cypress application. -> Controls every part of the test running process. - -## Install - -Root install is preferred (see `CONTRIBUTING.md`), but if you must - -* `npm install` -* `npm run build` - -## Testing - -* `npm run test-unit` executes unit tests (see `test/unit` folder) -* `npm run test-integration` executes integration tests -* `npm run test-e2e` executes the large (slow) end to end tests diff --git a/packages/socket/.release.json b/packages/socket/.release.json deleted file mode 100644 index ebded8e6e4..0000000000 --- a/packages/socket/.release.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "commitMessage": "release %s", - "tagAnnotation": "release %s", - "github": { - "release": false, - "releaseName": "release %s" - } -} diff --git a/packages/socket/README.md b/packages/socket/README.md index 21398b8e90..b66d23b845 100644 --- a/packages/socket/README.md +++ b/packages/socket/README.md @@ -1,7 +1,6 @@ -# Cypress Core Socket - -> This is a shared lib for holding both the `socket.io` server and client. +# Socket +This is a shared lib for holding both the `socket.io` server and client. ## Usage @@ -12,7 +11,7 @@ var socket = require("packages/core-socket") { server: require("socket.io"), client: require("socket.io-client"), - getPathToClientSource: function(){ + getPathToClientSource: function () { // returns path to the client 'socket.io.js' file // for use in the browser } @@ -40,19 +39,14 @@ socket.getPathToClientSource() ## Install -Root install is preferred (see `CONTRIBUTING.md`), but if you must - -* `npm install` - -## Development - -### Watching +The sockets's dependencies can be installed with: ```bash -npm run test-watch +cd packages/socket +npm install ``` -### Testing +## Testing ```bash npm test diff --git a/packages/socket/circle.yml b/packages/socket/circle.yml deleted file mode 100644 index 066007c545..0000000000 --- a/packages/socket/circle.yml +++ /dev/null @@ -1,5 +0,0 @@ -test: - override: - - nvm install 5.10 - - npm install - - npm run test-ci \ No newline at end of file