NYULibraries / primo-explore-views

A consolidated monorepo of NYU Consortium views
MIT License
2 stars 1 forks source link
nyulibraries-lits-webservices

NYU Consortium Primo Explore packages

Web Services

CircleCI Github commits (since latest release) Docker Repository on Quay

This the NYU Libraries primo-explore view packages.

For more information about primo-explore views please review the example package that this package was cloned from: https://github.com/ExLibrisGroup/primo-explore-package.

For information about developing in the primo-explore UI please review that relevant repository: https://github.com/ExLibrisGroup/primo-explore-devenv

For more information about NYU's customizations read the wiki.

Run the Development Environment

VIEW package files are organized into custom/VIEW_NAME directories.

With recommended volumes enabled in the docker-compose.yml:

With Docker and docker-compose installed:

  1. Configure docker-compose.yml to fit your institutional setup in the x-environment section. (docker-compose environment variables)
  2. Ensure volumes to local directories are configured in docker-compose.yml. The custom/ directory should be mounted to /app/primo-explore/custom in the image.
  3. NODE_ENV=[stage] VIEW=[view_name] docker-compose up web

On your local machine, the developer server will be accessible at http://localhost:8004/primo-explore/search?vid={VIEW}

Within the docker network, this will be accordingly be accessible at the address http://web:8004

The server will automatically refresh pages and reflect changes if CENTRAL_PACKAGE or your active view folder's (e.g. NYU for vid=NYU) files are changed.

Entry files

Run Tests

Integration and end-to-end testing has been implemented in Cypress. Cypress can run in its own container connected to a running web-test service.

Simply execute:

VIEW=[view_name] docker-compose run e2e

Tests will run in the Cypress Electron Browser so that videos and screenshots (on failures) are recorded. The default testing command in Docker runs tests matching the glob pattern cypress/integration/$VIEW/**/*.spec.js.

Between running tests, ensure that current docker containers are completely stopped with docker-compose down, or you may be running tests in a VIEW webserver you do not intend!

For convenience, script/run_view_e2e_tests.sh will run tests for files that have been changed in the current git branch relative to the cannonical state of origin/development. script/create_view_packages.sh does the same for building These are run on CirlcleCI. If on the master or development branch, all VIEW packages will be tested and built to ensure integrity.

See cypress command line documentation for more information.

Test records

BobCat dev holds a number of test items as relatively stable fixtures for testing. These are not consistent through their docids (e.g. nyu_aleph0000000) but they are consistent through their titles (e.g. PRIMOCIRCTEST-NABUD-MEDIA-02-LR).

Note: When an Aleph Staging refresh occurs, the tests need to be reconfigured with new IDs to pass again. You can look up those new IDs by the titles.

Note: There may be a delay between an Aleph Staging refresh and the test records reappearing on stage (due to required re-indexing and re-norming in Primo, a manual process for KARMS)

The test items we require on BobCatDev/AlephStage for our integration tests to run are as follows:

  1. Any record whose title includes "ALMATEST", for each of the supported views that we manage: BHS, CU, NYHS, NYSID, NYU, NYUAD, NYUSH. (We do a test search for "ALMATEST" in each view, which returns many results, so there's no need to document all the particular records that satisfy this)
  2. Any record whose title include "Work" and is available for course reserves ("always available online") for each of NYU, NYUAD, and NYUSH. Currently, this item is "Work" (nyu_aleph006297799)
  3. For custom requests tests, we refer to specific records by aleph ID (directly visiting the /fulldisplay page): "Documents algériens. Série politique." (nyu_aleph002138166), "ALMATEST NSHNG_PPL_ZZ_11 Loaned" (nyu_aleph009021088).

Cypress GUI (Running locally)

The Cypress GUI is accessible in a local development environment only, since a GUI is required.

yarn install
# Open Cypress GUI
yarn cypress open

This is extremely helpful for writing integration/end-to-end tests to see the consequences of your testing in real-time. See the Cypress documentation for information about the GUI and best practices in Cypress testing.

Build a Package

With recommended volumes enabled in the docker-compose.yml:

NODE_ENV=[stage] VIEW=[view_name] docker-compose run create-package

This will output a package to your ./packages/ directory in the container. Add volume mounting properties to your docker-compose.yml to acess these files on your local machine. Or, to copy them manually from the stopped container:

docker cp "$(docker ps -q -a -l -f name=create-package)":/app/packages/. packages

For convenience, script/create_package.sh is a sh script that will build all packages for files that have been changed in the current git branch relative to origin/master. This is used during the CI process. If on the master branch, all VIEW packages will be created with production values.

Yarn updates

Run yarn commands with the yarn service:

docker-compose run yarn install

Running locally

You can run the development environment locally using our fork of primo-explore-devenv as well, and symlinking this custom directory to that repostory's primo-explore/custom/ directory. However, because this monorepo is designed to work with yarn workspaces, this means that node_modules shared across packages will be installed (i.e. hoisted and deduped) to a parent directory. This means the monorepo's hoisted node_modules folder should also be symlinked to primo-explore/node_modules so they can be properly resolved.

# In primo-explore-views
yarn install
# In primo-explore-devenv
yarn install
VIEW=[view] NODE_ENV=[stage] yarn start

Other notes

This package has a loose 'monorepo' structure. Monorepos can sometimes have difficulties in resolving Node dependencies. yarn overcomes these problems using yarn workspaces. The basic important points are: