Playwright Tests for Aspen Discovery

This repository contains Playwright tests for use with Aspen Discovery.

🧬 Directory Structure

• 📁 /lib: Contains helper files for TypeScript architecture
• 📁 /page-objects: Contains repeat actions that can be used across tests, organized by the page on which they occur (e.g., Home, Grouped Works, etc.)
• 📁 /sites: Contains site-specific directories
  • 📁 /example: Example site directory
    • 📄 config.json: Example site configuration file
• 📁 /tests: Contains test suites, organized by related user behavior or workflows (e.g., Holds, Lists, etc.)
• 📄 .env.example: Example environment variables file
• 📄 playwright.config.ts: Playwright configuration file

🚀 Getting Started

1. Install Prerequisites

• Download Git
• Download Node.js

Note

If you're a testing librarian, you likely DON'T want the Docker version, so scroll down until you see "get a prebuilt Node.js® for..." and use that instead.

2. Clone the repository to your machine

Choose the method that sounds the easiest to you.

With GitHub Desktop

1. Install GitHub Desktop
2. Go to File > Clone repository
3. Use myr-onl/aspen-playwright-tests as the URL
4. Set your Local Path (this is where the repo will be copied)
5. Click Clone

Via command line

1. Open a terminal on your computer
2. Navigate to the folder where you want to copy this repo
3. Run git clone https://github.com/myr-onl/aspen-playwright-tests.git

3. Install node modules in the repository

1. Open the repo in your favorite IDE (e.g., VSCode, IntelliJ, etc.) and open its terminal OR open your computer terminal and navigate inside the repository
2. Run npm install

Important

If you are asked to install browsers with Playwright during install, say yes. If not, enter the command below to manually download them. These are testing browsers and not regular browsers that should appear in your computer applications list.

Install Playwright test browser(s)

npx playwright install

4. Create your site configuration file(s)

1. Copy the sites/example directory to a new directory
2. Name the new directory your intended site name (e.g. grove.production, aspen.localhost, etc.)
3. Open your new directory's config.json
4. Add your unique variables to the config file

Site configuration variables

• catalog: Basic info about your Aspen site
• url: Aspen home page URL
• ils: ILS that is connected to your Aspen (accepted values: `carlx`, `evergreen`, `evolve`, `koha`, `polaris`, `sierra`, or `symphony`)
• patron: A test patron with hold and checkout privileges in your ILS
• username: username or barcode
• password: password or PIN
• invalidPassword: incorrect password or PIN
• holdItem: A grouped work with a bib record in your ILS that can be placed on hold
• title: Title exactly as it appears within grouped work view
• format: Format label value exactly as it appears within grouped work view
• groupedWorkId: Unique ID for the grouped work (can be found in Staff view or grouped work URL)
• bibRecordId: Unique ID for the bib record (can be found with full record view URL)
• volumeHoldItem: A grouped work with a bib record in your ILS that has volume data and can be placed on hold
• Same variables as holdItem

5. Create your test configuration file

1. Copy the .env.example file to a new file called .env inside the root directory
2. Open .env
3. Set your environment variables

Environment variables

• SITE_NAME: Active site configuration against which to run tests
• ALLOW_MANUAL_REFRESH: Whether account data (like holds and checkouts) should be manually reloaded when performing tests
• ALLOW_VOLUME_HOLDS: Whether volume holds suite should be run

🏃 Running Test Suites

Open this repository inside your IDE and open its terminal OR open your computer terminal and navigate to be inside of this repository.

UI Mode (Recommended)

Running tests in UI mode gives you the most control over how tests are run and let's you inspect where failures have occurred as a snapshot. To open UI mode in a separate window, use the following command:

npx playwright test --ui

Headed Mode

Running tests in headed mode most closely resembles how we ran tests in the Selenium IDE browser extension. To watch your tests in real time using the base playwright.config.ts configuration, run:

npx playwright test --headed

Headless Mode

To run your tests in the background, run:

npx playwright test

Information about whether your tests passed or failed will display inside the terminal.

Once tests have finished, you can also view test results by running npx playwright show-report.