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 install chromedriver --cask # 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.

Selenium Testing Best Practices

Using Helper Methods for Waiting

For clarity and reliability, prefer using built-in helper methods instead of relying on numerous expect statements to handle asynchronous operations. Canvas provides many useful helper methods in spec/selenium/test_setup/common_helper_methods/ including:

• custom_wait_methods.rb - Contains wait_for, wait_for_new_page_load, and other waiting utilities
• custom_page_loaders.rb - Page loading and navigation helpers
• custom_selenium_actions.rb - Common Selenium actions
• custom_validators.rb - Validation helpers for Selenium tests

Using these helpers makes tests more readable and reliable than chains of expect statements.

Selenium-Specific Guidelines

• Use expect syntax: Use the expect(value).to matcher syntax consistently
• Organize with contexts: Use context blocks to describe different test scenarios
• Use let for test data: Use let to define reusable test data and objects