DLTS ReadiumJS viewer

Main repo for the building and testing of the DLTS ReadiumJS viewer used by NYU Press websites Open Square and Connected Youth.

See also: dlts-readium-cloud-reader-archive.

Prerequisities

• Bash (for Windows, try using the Git Bash that comes with git for Windows)

• Git

• NodeJS version 4.x or higher (for ES6 support). For doing NPM operations based on the package.json at the root of this repo, any NodeJS version higher than 4.x should be fine. However, if after running the build you wish to go inside the built ReadiumJS viewer instance to do the NPM tasks specified by Readium's repos, check the Prerequisites section of the ReadiumJS viewer README.md for information about which Node and NPM versions are recommended.

• Expect (if using the deploy shell scripts)

• yarn: see readium-js-viewer/package.json for required minimum version.

Installation and setup

git clone git@github.com:NYULibraries/dlts-readium-js-viewer.git
cd dlts-readium-js-viewer
npm install

Building the production ReadiumJS viewer

• To build the cloud-reader instance that is currently deployed to prod:

  npm run dist

• To verify that it is correct:

  npm run dist:verify

• To deploy to a host, copy readium-js-viewer/dist/cloud-reader/ to the proper location on the host.

Tests

Build

• To test that npm run dist builds a correct instance:

  npm run test:dist

  This runs npm run dist followed by npm run dist:verify.

Deploy

Deploy only after first running the build task. These deploy tasks by design do not include a build step. The commands for deploying to the dev, stage, and prod servers:

npm run deploy:dev

npm run deploy:stage

npm run deploy:prod

These tasks run the deploy scripts in scripts/ and then run the tests against the target server instance after the application has been deployed.

Automated browser tests

Selenium-driven UI tests of the DLTS build of ReadiumJS viewer are written using webdriver.io and mocha.

• To run the full test suite against a local instance of DLTS ReadiumJS viewer in both Chrome and Firefox simultaneously:

npm run test:browser:local

• To debug the tests for a specific browser:

npm run test:browser:local:debug:chrome

...or:

npm run test:browser:local:debug:firefox

These debug wdio configuration files set the test timeout to an extremely high value to allow for pausing at breakpoints and other line-debugging operations that would not be possible under normal timeout conditions.

• To run the tests against the dev, stage, and prod server application instances:

npm run test:browser:dev

npm run test:browser:stage

npm run test:browser:prod

• To run specific test suites, pass in the --suite option as specified in Group Test Specs:

# Run 3 tests suites against both Chrome and Firefox
npm run test:browser:local -- --suite navbar,navbarShowAndHide,settings

# Run a single test suite against either Chrome or Firefox
npm run test:browser:local:debug:chrome -- --suite youtube
npm run test:browser:local:debug:chrome -- --suite toc

The suites property in test/browser/conf/wdio.main.conf.js contains the definitions for the available test suites.

Note on Firefox testing

Mozilla uses automation protocol Marionette. Selenium being WebDriver-based needs to use the WebDriver <-> Marionette proxy geckodriver which is not yet feature complete -- see WebDriver Status. As a result, Firefox testing tends to be a bit trickier.

Test flake

Note that Chrome fullscreen tests will always fail in headless mode. This command can be used to run properly test fullscreen functionality:

npm run test:browser:local:debug:chrome -- --suite fullscreen

The is also a non-deterministic error that can pop up when running the YouTube video tests in Firefox: "TypeError: can't access dead object". This could be the result of an outstanding geckodriver bug: "TypeError: can't access dead object" if the frame is removed from under us #614.

If experiencing flake while running tests other than these, try lowering the value of maxInstances in wdio.main.conf.js to reduce concurrency. In theory there shouldn't be any interference caused by running the test suites concurrently in many browser instances, but in practice it does seem to reduce test flake, particularly on less powerful machines.