Testing Guide

This guide covers running and writing tests for the Open Library project.

Running Tests

When to Use What

Scenario	Command
Full test suite (before opening a PR)	make test
Python-only changes	pytest
JavaScript-only changes	npm run test
Type checking Python	make mypy

All commands below run inside docker compose run --rm home.

Run All Tests

Runs the full test suite — Python tests, JavaScript tests, and type checks. Use this before opening a PR or when your changes touch multiple parts of the codebase.

docker compose run --rm home make test

Run Python Tests Only

Use pytest when your changes only affect Python files. This is faster than running the full suite.

docker compose run --rm home pytest

Run a specific test file:

docker compose run --rm home pytest openlibrary/plugins/importapi/tests/test_import_validator.py

Run tests matching a pattern:

docker compose run --rm home pytest -k "test_name_pattern"

Run JavaScript Tests

Use npm run test when your changes only affect JavaScript or CSS files.

docker compose run --rm home npm run test

Run Type Checks

Runs mypy type checking on the Python codebase.

docker compose run --rm home make mypy

Linting

Open Library uses automated linting to maintain code quality and consistency. The CI server automatically checks all pull requests for linting issues. To save time, you can run these checks locally before pushing your changes.

Quick Reference

Task	Command
Run all linters	docker compose run --rm home make lint
Lint JavaScript	docker compose run --rm home npm run lint
Lint Python	docker compose run --rm home make lint
Run pre-commit hooks	pre-commit run --all-files
Bypass pre-commit	git commit --no-verify

For details on setting up and troubleshooting pre-commit, see the Pre-Commit Guide.

Manual Testing

When testing changes locally, use these pages to verify your work. All URLs assume a local dev server at localhost:8080.

Having trouble accessing a page?

If you can't reach a page due to permissions, missing data, or anything else, reach out to us on Slack and we'll help you get set up.

Core Record Pages

Page	URL	Notes
Book (edition)	/books/OL{ID}M	Individual edition with cover, metadata, borrow/read options
Work	/works/OL{ID}W	Groups all editions of a book
Author	/authors/OL{ID}A	Bio, photo, and list of works
Subject	/subjects/{name}	Browse books by topic, e.g. /subjects/fiction
Tag	/tag/{name}	View a tag page
Add Tag	/tag/add	Create a new tag

Search & Discovery

Page	URL	Notes
Search	/search?q={query}	Main book search
Search (JSON)	/search.json?q={query}	API endpoint for search results
Trending	/trending	Popular books
Homepage	/	Featured content and carousels

User & Reading Log

Page	URL	Notes
Login	/account/login
Register	/account/create
Profile	/people/{username}	Public user profile
My Books	/people/{username}/books	Reading log overview
Want to Read	/people/{username}/books/want-to-read
Currently Reading	/people/{username}/books/currently-reading
Already Read	/people/{username}/books/already-read
Lists	/people/{username}/lists	User-created lists
Loans	/account/loans	Active loans (logged-in user)

Editing & Imports

Page	URL	Notes
Add a Book	/books/add	Manual book creation form
Edit Edition	/books/OL{ID}M/edit	Edit an existing edition
Edit Work	/works/OL{ID}W/edit	Edit an existing work
ISBN Lookup	/isbn/{isbn}	Lookup or import by ISBN
Import API	/api/import	JSON import endpoint

Info Pages

Page	URL	Notes
About	/about
Help	/help
Recent Changes	/recentchanges	Recent edits across the site
Stats	/stats	Site-wide statistics
Lending Stats	/stats/lending

API Endpoints

Endpoint	Notes
/api/books	Books API
/api/search	Search API
/api/import	Import API
/api/import/ia	Archive.org item import
/search.json	Search results as JSON

TIP

URL ID formats: OL + number + type letter — A (author), W (work), M (edition). For example, OL1234W is a work and OL5678M is an edition.