From db1d410c194c1e54620ad2b1dfc7a3ca97510a71 Mon Sep 17 00:00:00 2001 From: Charles Suttie Date: Sat, 7 Jul 2018 22:11:21 +1000 Subject: [PATCH] docs: update ci story update the CircleCi and Travis configurations update ng test and ng e2e command flags for version 6 use headless chrome instead of chrome add guidance on ChromeDriver closes #10677 --- .../stories/continuous-integration.md | 80 +++++++++++-------- 1 file changed, 48 insertions(+), 32 deletions(-) diff --git a/docs/documentation/stories/continuous-integration.md b/docs/documentation/stories/continuous-integration.md index 0de351a21c38..269bab08997c 100644 --- a/docs/documentation/stories/continuous-integration.md +++ b/docs/documentation/stories/continuous-integration.md @@ -23,22 +23,24 @@ set up Circle CI and Travis CI. Even though `ng test` and `ng e2e` already run on your environment, they need to be adjusted to run in CI environments. -When using Chrome in CI environments it has to be started without sandboxing. -We can achieve that by editing our test configs. +We'll use [Headless Chrome](https://developers.google.com/web/updates/2017/04/headless-chrome#cli) in CI environments. In some environments we need to start the browser without +sandboxing or disable the gpu. Here we'll do both. -In `karma.conf.js`, add a custom launcher called `ChromeNoSandbox` below `browsers`: +In `karma.conf.js`, add a custom launcher called `ChromeHeadlessCI` below `browsers`: ``` browsers: ['Chrome'], customLaunchers: { - ChromeNoSandbox: { - base: 'Chrome', - flags: ['--no-sandbox'] + ChromeHeadlessCI: { + base: 'ChromeHeadless', + flags: ['--no-sandbox', '--disable-gpu'] } }, ``` -Create a new file in the root of your project called `protractor-ci.conf.js`, that extends +We'll override the `browsers` option from the command line to use our new configuration. + +Create a new file in the `e2e` directory of your project called `protractor-ci.conf.js`, that extends the original `protractor.conf.js`: ``` @@ -47,22 +49,24 @@ const config = require('./protractor.conf').config; config.capabilities = { browserName: 'chrome', chromeOptions: { - args: ['--no-sandbox'] + args: ['--headless', '--no-sandbox', '--disable-gpu'] } }; exports.config = config; ``` -Now you can run the following commands to use the `--no-sandbox` flag: +Now you can run the following commands to use the new configurations: ``` -ng test --no-watch --no-progress --browser=ChromeNoSandbox -ng e2e --no-progress --config=protractor-ci.conf.js +ng test --watch=false --progress=false --browsers=ChromeHeadlessCI +ng e2e --protractor-config=./e2e/protractor-ci.conf.js ``` -For CI environments it's also a good idea to disable progress reporting (via `--no-progress`) -to avoid spamming the server log with progress messages. +For CI environments it's also a good idea to disable progress reporting (via `--progress=false`) +to avoid spamming the server log with progress messages. We've added that option to `ng test`. An equivalent +option has been requested for +`ng e2e` [(#11412)](https://github.com/angular/angular-cli/issues/11412). ## Using Circle CI @@ -76,28 +80,27 @@ jobs: build: working_directory: ~/my-project docker: + # specify the version you desire here + # see https://hub.docker.com/r/circleci/node/tags/ - image: circleci/node:8-browsers steps: - checkout - restore_cache: - key: my-project-{{ .Branch }}-{{ checksum "package.json" }} + key: my-project-{{ .Branch }}-{{ checksum "package-lock.json" }} - run: npm install - save_cache: - key: my-project-{{ .Branch }}-{{ checksum "package.json" }} + key: my-project-{{ .Branch }}-{{ checksum "package-lock.json" }} paths: - - "node_modules" - - run: xvfb-run -a npm run test -- --no-watch --no-progress --browser=ChromeNoSandbox - - run: xvfb-run -a npm run e2e -- --no-progress --config=protractor-ci.conf.js - + - "node_modules" + - run: npm run test -- --watch=false --progress=false --browsers=ChromeHeadlessCI + - run: npm run e2e -- --protractor-config=./e2e/protractor-ci.conf.js ``` We're doing a few things here: - - `node_modules` is cached. - - [npm run](https://docs.npmjs.com/cli/run-script) is used to run `ng` because `@angular/cli` is + - we use [npm run](https://docs.npmjs.com/cli/run-script) to run `ng` because `@angular/cli` is not installed globally. The double dash (`--`) is needed to pass arguments into the npm script. - - `xvfb-run` is used to run `npm run` to run a command using a virtual screen, which is needed by - Chrome. Commit your changes and push them to your repository. @@ -119,7 +122,7 @@ sudo: false language: node_js node_js: - "8" - + addons: apt: sources: @@ -135,17 +138,10 @@ install: - npm install script: - # Use Chromium instead of Chrome. - - export CHROME_BIN=chromium-browser - - xvfb-run -a npm run test -- --no-watch --no-progress --browser=ChromeNoSandbox - - xvfb-run -a npm run e2e -- --no-progress --config=protractor-ci.conf.js - + - npm run test -- --watch=false --progress=false --browsers=ChromeHeadlessCI + - npm run e2e -- --protractor-config=./e2e/protractor-ci.conf.js ``` -Although the syntax is different, we're mostly doing the same steps as were done in the -Circle CI config. -The only difference is that Travis doesn't come with Chrome, so we use Chromium instead. - Commit your changes and push them to your repository. Next you'll need to [sign up for Travis CI](https://travis-ci.org/auth) and @@ -153,3 +149,23 @@ Next you'll need to [sign up for Travis CI](https://travis-ci.org/auth) and You'll need to push a new commit to trigger a build. Be sure to check out the [Travis CI docs](https://docs.travis-ci.com/) if you want to know more. + +## ChromeDriver + +In CI environments it's a good idea to to use a specific version of [ChromeDriver](http://chromedriver.chromium.org/) +instead of allowing `ng e2e` to use the latest one. CI environments often use older versions of chrome, which are unsupported by newer versions of ChromeDriver. + +An easy way to do this is to define a NPM script: + +```text +"webdriver-update-ci": "webdriver-manager update --standalone false --gecko false --versions.chrome 2.37" +``` + +And then on CI environments you call that script followed by the e2e command without updating webdriver: + +```text +npm run webdriver-update-ci +ng e2e --webdriver-update=false +``` + +This way you will always use a specific version of chrome driver between runs. \ No newline at end of file