From d39b927c3ae797bf8afb337227d764e000496a38 Mon Sep 17 00:00:00 2001 From: Michael Ziwisky Date: Wed, 6 Jan 2021 00:57:21 -0800 Subject: [PATCH] update JS testing docs flag=none this commit also removes the phantomjs docker-compose service which has been broken for years, ever since PhantomJS was removed from karma.conf.js in https://gerrit.instructure.com/c/canvas-lms/+/102169 test plan: - follow the docs to ensure you can run a targeted JS test in docker Change-Id: Ifa1647897a7a9605e097aeaf89e718c167d379fc Reviewed-on: https://gerrit.instructure.com/c/canvas-lms/+/256179 Reviewed-by: Nate Armstrong QA-Review: Nate Armstrong Tested-by: Service Cloud Jenkins Product-Review: Michael Ziwisky --- doc/docker/developing_with_docker.md | 50 ++++++++++++- doc/testing_javascript.md | 75 ++----------------- .../js-phantomjs-tests.override.yml | 17 ----- docker-compose/phantomjs-karma/Dockerfile | 31 -------- docker-compose/phantomjs-karma/entry_point.sh | 2 - package.json | 1 + 6 files changed, 54 insertions(+), 122 deletions(-) delete mode 100644 docker-compose/js-phantomjs-tests.override.yml delete mode 100644 docker-compose/phantomjs-karma/Dockerfile delete mode 100755 docker-compose/phantomjs-karma/entry_point.sh diff --git a/doc/docker/developing_with_docker.md b/doc/docker/developing_with_docker.md index aa40350a3ae..14e2c922ebe 100644 --- a/doc/docker/developing_with_docker.md +++ b/doc/docker/developing_with_docker.md @@ -158,14 +158,56 @@ $ docker-compose run --rm web bundle exec rspec spec ## Running javascript tests -To run tests in headless Chrome, add the `docker-compose/js-tests.override.yml` -to the `COMPOSE_FILE` environment variable in your .env, and run: +First off, there's some general JS testing info in +[testing_javascript.md](https://github.com/instructure/canvas-lms/blob/master/doc/testing_javascript.md). +That will guide you on running JS tests natively. To run them in docker, read on. + +First add `docker-compose/js-tests.override.yml` to your `COMPOSE_FILE` var in +`.env`. Then prepare that container with: ``` -$ docker-compose run --rm js-tests +docker-compose run --rm js-tests yarn install ``` -### Selenium +If you run into issues with that command, either during initial setup or after +updating master, try to fix it with a `nuke_node`: + +``` +docker-compose run --rm js-tests ./script/nuke_node.sh +docker-compose run --rm js-tests yarn install +``` + +### QUnit Karma Tests in Headless Chrome + +Run all QUnit tests in watch mode with: + +``` +docker-compose run --rm js-tests +``` + +Or, if you're iterating on something and want to just run a targeted test file +in watch mode, set the `JSPEC_PATH` env var, e.g.: + +``` +docker-compose run --rm -e JSPEC_PATH=spec/coffeescripts/util/deparamSpec.js js-tests +``` + +### Jest Tests + +Run all Jest tests with: + +``` +docker-compose run --rm js-tests yarn test:jest +``` + +Or to run a targeted subset of tests in watch mode, use `test:jest:watch` and +specify the paths to the test files as one or more arguments, e.g.: + +``` +docker-compose run --rm js-tests yarn test:jest:watch app/jsx/actAs/__tests__/ActAsModal.test.js +``` + +## Selenium To enable Selenium: Add `docker-compose/selenium.override.yml` to your `COMPOSE_FILE` var in `.env`. diff --git a/doc/testing_javascript.md b/doc/testing_javascript.md index 8e925580f6a..60fac1089c1 100644 --- a/doc/testing_javascript.md +++ b/doc/testing_javascript.md @@ -11,7 +11,7 @@ stuff from app/jsx or node_modules), you should write your js tests for Jest is a Node-based runner. This means that the tests always run in a Node environment and not in a real browser. This lets us enable fast iteration speed and prevent flakiness. -While Jest provides browser globals such as `window` thanks to [jsdom](https://github.com/tmpvar/jsdom), they are only approximations of the real browser behavior. Jest is intended to be used for unit tests of your logic and your components rather than the DOM quirks. Use a qUnit karma test or selenium for browser end-to-end tests if you need them. +While Jest provides browser globals such as `window` thanks to [jsdom](https://github.com/tmpvar/jsdom), they are only approximations of the real browser behavior. Jest is intended to be used for unit tests of your logic and your components rather than the DOM quirks. Use a QUnit Karma test or Selenium for browser end-to-end tests if you need them. ### Filename Conventions @@ -114,80 +114,19 @@ your components and saves them on the disk so if the UI output changes, you get notified without manually writing any assertions on the component output. [Read more about snapshot testing.](http://facebook.github.io/jest/blog/2016/07/27/jest-14.html) -## With Docker and headless Chrome +## Running QUnit Karma Tests -This is probably the easiest way to run tests, especially for developers that -don't work with Canvas on a regular basis. +A lot of the older stuff is still QUnit. For more info on running those older tests, see the "Running js tests with webpack" section of [working_with_webpack.md](https://github.com/instructure/canvas-lms/blob/master/doc/working_with_webpack.md). -Create a `.env` file in the repository root, containing: +Tl;dr: run a single test in watch mode like: ``` -COMPOSE_FILE=docker-compose.yml:docker-compose.override.yml:docker-compose/js-tests.override.yml +yarn jspec-watch spec/coffeescripts/util/deparamSpec.js ``` -Then run: +## Running Tests in Docker -``` -docker-compose run --rm js-tests -``` - -## With Docker and Webpack - -This is becoming the go to standard for running Canvas and compiling your not-JavaScript -(CoffeeScript, JSX, Handlebars, etc.) code into JavaScript code. You should likely -be following this path when doing front-end development on Canvas. If you need help -getting started with that please see [development_with_docker.md](https://github.com/instructure/canvas-lms/blob/master/doc/development_with_docker.md) -and [working_with_webpack.md](https://github.com/instructure/canvas-lms/blob/master/doc/working_with_webpack.md). - -Before we can get started in earnest, we need to make a few changes to a couple -of files. Inside your `.env` file, add the phantomjs-tests override in your -`COMPOSE_FILE` definition: `docker-compose/js-phantomjs-tests.override.yml` - -### JSpec - -The `jspec` npm script allows you to build and run specific JavaScript specs as follows: - -1) `yarn run jspec path/to/specs` - This will build the specified specs using webpack and run them locally using Chrome. - - You can specify a directory or a single spec file to build and run. If no path - is provided, all javascript specs are built and ran. - -2) `yarn run jspec-watch path/to/specs` - This will get webpack building the specified specs in watch mode, making it so your - changes are instantly (or close to instantly) reflected in the test bundle. - - You can specify a directory or a single spec file to watch and build. If no path - is provided, all javascript specs are watched and built. - - Using `jspec` in this way assumes you will run the specs yourself using PhantomJS - (see below) or by using `yarn test` to run them locally in Chrome. - -### PhantomJS - -To run javascript specs using PhantomJS you can do so as follow: - -1) `yarn run jspec-watch path/to/specs` - This will get webpack building the test bundle in watch mode, making it so your - changes are instantly (or close to instantly) reflected in the test bundle. - - You can specify a directory or a single spec file to watch and build. If no path - is provided, all javascript specs are watched and built. - -2) `docker-compose run --rm phantomjs-tests` - This will start the PhantomJS container in watch mode running the test bundle - anytime the test bundle gets updated. - -So you'll now see PhantomJS almost instantly complete the test suite for you. -Unfortunately, you'll also see some failures :(. Don't worry though! The reason -you see failures is the lack of full support for some browser standards in PhantomJS. -We don't polyfill for PhantomJS (at least when this is being written) so you'll generally -see a few failures there. - -Now navigate in your browser to http://phantom.docker and your tests will run inside -the browser you have open (in addition to PhantomJS). This will give you the chance -to debug them as well as see how they work in a fully functional browser. Our JS -specs currently run in Chrome so make sure that your tests pass there. +See the "Running javascript tests" section of [developing_with_docker.md](https://github.com/instructure/canvas-lms/blob/master/doc/docker/developing_with_docker.md). ## Javascript Test Coverage diff --git a/docker-compose/js-phantomjs-tests.override.yml b/docker-compose/js-phantomjs-tests.override.yml deleted file mode 100644 index 04330402c82..00000000000 --- a/docker-compose/js-phantomjs-tests.override.yml +++ /dev/null @@ -1,17 +0,0 @@ -# to use this add docker-compose/js-phantomjs-tests.override.yml -# to your COMPOSE_FILE var in .env - -version: '2.3' -services: - phantomjs-tests: - build: ./docker-compose/phantomjs-karma - volumes: - - .:/app - - generated_1:/app/public/javascripts/client_apps - - generated_2:/app/public/dist - - i18nliner_node_modules:/app/gems/canvas_i18nliner/node_modules - - node_modules:/app/node_modules - - quizzes_node_modules:/app/client_apps/canvas_quizzes/node_modules - environment: - NODE_ENV: CI - VIRTUAL_HOST: phantom.docker diff --git a/docker-compose/phantomjs-karma/Dockerfile b/docker-compose/phantomjs-karma/Dockerfile deleted file mode 100644 index d7c9bdb0835..00000000000 --- a/docker-compose/phantomjs-karma/Dockerfile +++ /dev/null @@ -1,31 +0,0 @@ -FROM ubuntu:trusty -MAINTAINER Instructure - -# Env -ENV PHANTOMJS_VERSION 2.1.1 - -RUN \ - apt-get update -yqq && \ - apt-get install -fyqq wget curl libfreetype6 libfontconfig - -RUN curl -sL https://deb.nodesource.com/setup_10.x | bash - -RUN apt-get update -qq \ - && apt-get install -qqy nodejs - - -RUN \ - mkdir -p /srv/var && \ - wget -q --no-check-certificate -O /tmp/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 && \ - tar -xjf /tmp/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 -C /tmp && \ - rm -f /tmp/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 && \ - mv /tmp/phantomjs-$PHANTOMJS_VERSION-linux-x86_64/ /srv/var/phantomjs && \ - ln -s /srv/var/phantomjs/bin/phantomjs /usr/bin/phantomjs - -EXPOSE 9876 - -RUN mkdir /app -WORKDIR /app - -COPY entry_point.sh /opt/bin/entry_point.sh - -ENTRYPOINT ["/opt/bin/entry_point.sh"] diff --git a/docker-compose/phantomjs-karma/entry_point.sh b/docker-compose/phantomjs-karma/entry_point.sh deleted file mode 100755 index 1fb70b80bc8..00000000000 --- a/docker-compose/phantomjs-karma/entry_point.sh +++ /dev/null @@ -1,2 +0,0 @@ -#!/bin/bash -./node_modules/karma/bin/karma start --browsers PhantomJS --reporters progress 2>&1 diff --git a/package.json b/package.json index d27610d8fc4..0e91bdab8d3 100644 --- a/package.json +++ b/package.json @@ -305,6 +305,7 @@ "test:jest": "jest --color", "test:jest:coverage": "NODE_OPTIONS=\"--max_old_space_size=8192\" jest --color --coverage", "test:jest:debug": "node --inspect-brk node_modules/.bin/jest --runInBand", + "test:jest:watch": "jest --color --watch", "test:karma": "yarn run test:karma:watch --single-run", "test:karma:concurrently": "concurrently --names \"coffee,jsa,jsg,jsh\" \"JSPEC_GROUP=coffee yarn test:karma:headless\" \"JSPEC_GROUP=jsa yarn test:karma:headless\" \"JSPEC_GROUP=jsg yarn test:karma:headless\" \"JSPEC_GROUP=jsh yarn test:karma:headless\"", "test:karma:headless": "yarn run test:karma --browsers ChromeHeadlessNoSandbox",