How to Run GeoLibre's Test Suites: TSX Frontend Tests and Pytest Backend Tests Explained

GeoLibre uses tsx for its TypeScript frontend unit tests, pytest for its Python FastAPI backend tests, and Playwright for end-to-end testing, all orchestrated through npm scripts in the root package.json.

GeoLibre is a polyglot monorepo maintained by opengeos that combines a modern TypeScript-centric frontend with a Python backend. This architecture requires multiple testing frameworks working together. Understanding how to run GeoLibre's test suites ensures you can validate changes across both the frontend TSX components and the backend Python services before committing code.

Testing Architecture Overview

GeoLibre organizes its testing across three distinct layers. Each layer uses purpose-built tools optimized for its environment.

Component	Framework	Entry Command	Key Location
Frontend unit tests	node --test with tsx loader	npm run test:frontend	tests/*.test.ts
Backend unit tests	pytest	npm run test:backend	backend/geolibre_server/tests/
End-to-end tests	Playwright	npm run test:e2e	e2e/*.spec.ts
Coverage reporting	Node coverage / pytest-cov	:coverage variants of above	—

The frontend tests are written in TSX (TypeScript with JSX support) so React components can be exercised directly. The tsx loader is automatically engaged by the node --test command, which recognizes files ending in .test.ts or .test.tsx according to the repository's configuration.

Prerequisites: Installing Dependencies

Before running any GeoLibre test suites, ensure both Node.js and Python dependencies are fully installed.

cd /path/to/GeoLibre
npm install
pip install -e "backend/geolibre_server[test]"

The npm install at the root wires together every workspace in the monorepo. The pip install command installs the FastAPI backend with its test extras, including pytest and pytest-cov as specified in the backend's pyproject.toml.

Running Frontend TSX Tests

Basic Frontend Test Execution

Execute all TypeScript frontend unit tests with the standard npm script:

npm run test:frontend

This invokes node --test with the tsx loader across all files matching tests/*.test.ts. In package.json, this script is defined to automatically handle the TypeScript compilation overhead.

Frontend Coverage Reports

To run tests with coverage enforcement (fails below configured thresholds):

npm run test:frontend:coverage

The coverage configuration is defined in the repository root and integrates with Node's native coverage tooling.

Running a Single Frontend Test File

For targeted debugging, invoke the test runner directly with a specific file path:

node --import tsx --test tests/expressions.test.ts

The --import tsx flag ensures TypeScript and JSX syntax are properly transpiled without precompilation. The file tests/expressions.test.ts serves as the primary frontend test entry point in the GeoLibre repository.

Running Backend Pytest Tests

Basic Backend Test Execution

Run the complete pytest suite against the FastAPI sidecar:

npm run test:backend

This npm script delegates to pytest with the appropriate Python path and configuration. The test discovery starts from backend/geolibre_server/tests/ as configured in the pytest setup.

Backend Coverage Reports

For coverage-validated backend testing:

npm run test:backend:coverage

This utilizes pytest-cov with threshold enforcement configured for the geolibre_server package.

Running Specific Backend Tests

Target individual test files or cases for faster iteration:

python -m pytest backend/geolibre_server/tests/test_vector.py
python -m pytest backend/geolibre_server/tests/test_vector.py::test_vector_transform

The test_vector.py file contains tests for the vector transformation pipeline, a core backend capability.

Running Playwright End-to-End Tests

Full E2E Suite Execution

Validate the complete user interface workflow:

npm run test:e2e

This command performs three operations automatically:

1. Builds the web application for production
2. Serves the build with vite preview
3. Executes the Playwright test suite against the running server

Prerequisites for E2E Testing

First-time Playwright execution requires browser binaries:

npx playwright install chromium

E2E Test Customization

Pass additional flags through npm's argument forwarding:

npm run test:e2e -- --browser=chromium --headless

The E2E test specifications reside in the e2e/ directory, with record-video.spec.ts demonstrating video capture capabilities for debugging test failures.

Key Configuration Files and Test Locations

Understanding the repository structure helps locate tests and configuration:

• CLAUDE.md — Central reference document defining all repository commands including precise test script flags
• tests/expressions.test.ts — Exemplar frontend TSX test demonstrating component testing patterns
• backend/geolibre_server/tests/ — Complete pytest collection covering the FastAPI sidecar, conversion utilities, and vector/raster pipelines
• e2e/ — Playwright specifications for UI smoke testing
• package.json (root) — Central command definitions for all test suites across workspaces

Summary

• GeoLibre's frontend tests use tsx with Node's native test runner, executed via npm run test:frontend
• Backend tests use pytest for the FastAPI Python services, executed via npm run test:backend
• E2E tests use Playwright for full UI validation, executed via npm run test:e2e
• Install dependencies with npm install and pip install -e "backend/geolibre_server[test]" before testing
• Coverage enforcement is available for both frontend (:coverage suffix) and backend test suites
• Run individual tests by passing specific file paths to node --import tsx --test or python -m pytest

Frequently Asked Questions

Does GeoLibre use Jest for frontend testing?

No. GeoLibre uses Node's built-in test runner with the tsx loader rather than Jest. The npm run test:frontend command executes node --test directly, which provides native TypeScript and JSX support through the tsx package without additional test framework overhead.

Why does GeoLibre require both npm and pip to run tests?

GeoLibre is a polyglot monorepo. The frontend is TypeScript/React requiring Node.js dependencies, while the backend is a Python FastAPI service. The npm run test:backend script orchestrates pytest execution, but the Python environment and packages must be installed separately via pip.

How do I run only the vector pipeline tests in the backend?

Target the specific test module directly with pytest: python -m pytest backend/geolibre_server/tests/test_vector.py. For a single test case, append the double-colon syntax: ::test_vector_transform to the module path.

What coverage thresholds does GeoLibre enforce?

Both frontend and backend coverage commands fail builds when thresholds are not met. The exact percentage thresholds are configured in the repository's coverage configuration files—consult CLAUDE.md in the repository root for the specific values and any per-directory overrides.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}