canvas-lms/doc/testing_with_selenium.md

Testing with Selenium

You may run the Selenium tests either natively or in docker.

Running Selenium Tests Natively (Mac)

We're making a few assumptions here:

• you're using an Apple computer
• you've already installed Homebrew
• you've already installed Postgres (postgresapp.com is an excellent option), and Postgres is running on your computer
• you've already installed Node.js

0. Install yarn if you haven't already:

brew install yarn

If you find you need an older version of yarn, follow these instructions to install the older version and switch to it:

https://stackoverflow.com/a/52525732/3038677

1. Follow the instructions in script/prepare/README.md to setup the prepare script.

You'll use the prepare script later to automate installing and updating Canvas on your computer.

Note: some features of prepare only work if you have access to Instructure's Gerrit host. See the README for details.

2. Install a web browser driver on your computer for the browser you wish to run the tests in. Homebrew is the easiest way to go:

brew cask install chromedriver # necessary for running tests in Chrome
brew install geckodriver # necessary for running tests in Firefox

Now let's get Canvas ready to run the tests.

3. Copy the Selenium and database configuration files:

cp config/selenium.yml.example config/selenium.yml
cp config/database.yml.example config/database.yml

4. Use prepare to install Canvas plugins and dependencies, create databases, run database migrations, etc:

prepare

You might encounter problems with some Ruby dependencies. The "Dependency Installation" section in the public Canvas LMS Github wiki has some useful tips.

4.a. Optional. Run delayed jobs in the foreground (not all Selenium tests need this but some do):

script/delayed_job run

or run it in the background:

script/delayed_job run &

5. Run the Selenium tests:

bundle exec rspec spec/selenium

or run a specific Selenium test:

bundle exec rspec spec/selenium/accounts_spec.rb:36

Running Tests against Headless Chrome

Selenium tests can be run against headless Chrome by changing a few properties in config/selenium.yml. Specifically, you'll need to set headless to true and window_size to something that makes sense, like so:

  headless: true
  window_size: "1237,974"

This can be useful when you don't need to see what your test is doing, since it can run in the background without stealing focus or interrupting other work. It's especially useful when running specs many times to check for flakiness.

Running Selenium Tests in Docker

See the Selenium section of the doc/docker/developing_with_docker.md instructions.