openstax / tutor-js

:mortar_board: Javascript frontend for openstax tutor

TutorJS

The Front-end code for Openstax Tutor related projects

Install

1. install nvm

• run nvm install in this directory to install and use the correct version of node
• Alternatively: manually install the right version of node in ./.nvmrc

1. Git Clone this repository to the directory of your choice

• If you don’t have git installed you can install homebrew and then brew install git

1. cd tutor-js move into the checked out directory
2. yarn install
3. yarn run serve <project> (where <project is one of tutor|exercises)

• Run the Tutor server as shown below

Development

• yarn run serve <project> starts up a local development webserver which rebuilds files when changed.
• yarn test <project> runs unit tests for all projects
• yarn run coverage generates a code coverage report
• yarn run build <project> archive builds minified files for production
• yarn run test e2e run the integration tests using playwright test runner.

e2e test failures

To debug e2e failures, you can run in debug mode by adding the --debug flag. For instance to debug a failure with the course roster spec, you could run: yarn run test e2e --debug roster. --debug disables timeouts and is useful in conjuction with adding strategic page.pause() calls in the spec. The brower will then open and pause at that step, allowing you to open the browser console and inspect it's state.

On Github actions you can download the "test-result" artifacts. Each test failure will generate a screenshot and a trace file. The trace file can be viewed by: yarn run playwright show-trace <path to trace file> The viewer allows you to view the browser screen and dev console for each test step.

There is also a retries configration that can be adjusted if some specs are inherently flaky.

After local updates are made:

1. stop yarn start
2. yarn install
3. restart yarn start

Playwright tests

Tutor uses playwright for acceptance testing. The tests can be ran by:

1. start the stubbed backend server: yarn run tutor:test:server
2. run the e2e test suite: yarn run tutor:test:e2e

Tutor Server

Using the sample API data only allows acting as a student and can't save data. For a more realistic development experience you'll also need to run the Tutor server

1. Install Tutor Server as shown in its README file
2. Start both the tutor-server Rails application and run yarn run serve tutor in this project's directory
3. Load http://localhost:3001 in your browser

• Once you click login, the server will present a dev console that allows you to select a user

1. And will then render the FE just as it appears in production

Exercises

tutor-js is also the front-end for Exercises and is ran similarly to the Tutor Server.

1. Install OpenStax Exercises as shown in its README file
2. Run yarn run serve exercises in tutor-js directory
3. Load http://localhost:3000 in your browser