How to Run the Unit Tests for GeoLibre: A Complete Guide for All Test Layers

Run GeoLibre's unit tests using npm scripts that cover the frontend (npm run test:frontend), Python backend (npm run test:backend), workers (npm run test:worker), and end-to-end suites (npm run test:e2e).

GeoLibre is a geospatial desktop application built as a monorepo with TypeScript frontend code, Python FastAPI backend services, and Web Worker architectures. Understanding how to run the unit tests for GeoLibre ensures you can validate changes across all these layers before contributing or deploying. This guide walks through each test suite with exact commands and file references from the opengeos/GeoLibre repository.

Test Suite Architecture Overview

GeoLibre organizes tests into four distinct layers that mirror its technical stack:

Test Layer	Technology	Entry Point	Purpose
Frontend	Node.js built-in test runner + tsx	package.json → "test:frontend"	Browser/UI code, store logic, WASM conversions
Backend	pytest	package.json → "test:backend"	FastAPI server, vector/raster utilities
Workers	Node.js + TypeScript checking	package.json → "test:worker"	Web Workers (viewer, collab, tiles, AI-proxy)
End-to-End	Playwright	package.json → "test:e2e"	Full browser automation tests

Prerequisites: Repository Setup

Before running any GeoLibre unit tests, complete the environment setup:

1. Clone the repository

git clone https://github.com/opengeos/GeoLibre.git
cd GeoLibre

2. Install Node workspace dependencies

npm install

This resolves all workspaces under apps/*, packages/*, and workers/* as defined in the root package.json.

3. Install Python backend test dependencies (required for backend coverage)

pip install -e "backend/geolibre_server[test]"

The [test] extras install pytest, pytest-cov, and heavy geospatial libraries including geopandas and rasterio. The repository's CLAUDE.md explicitly documents this requirement when working with the Python side-car.

Running the Frontend Unit Tests

The frontend test suite covers all TypeScript/JavaScript code that runs in the browser or Tauri desktop shell.

Execute with:

npm run test:frontend

Under the hood, this runs:

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

The tsx loader compiles .ts and .tsx files on-the-fly, so no separate build step is needed. Tests are discovered in the top-level tests/ directory. For example, tests/wasm-convert.test.ts exercises the WASM-based vector and raster conversion tools.

Running the Backend Unit Tests

The Python backend uses FastAPI to provide conversion, vector, and raster utilities.

Execute with:

npm run test:backend

This forwards to:

python -m pytest backend/geolibre_server/tests --cov-fail-under=55

The command enforces a 55% line coverage floor and generates a coverage report. Test files live in backend/geolibre_server/tests/ and cover the full API surface of the side-car server.

Running the Worker Tests

Worker tests validate the TypeScript code running in dedicated Web Workers for viewer rendering, collaboration, tile management, and AI proxying.

Execute with:

npm run test:worker

This command performs two operations:

• Type-checks each worker workspace (e.g., workers/viewer, workers/collab)
• Executes Node-based tests within worker packages

The dual validation ensures both compile-time correctness and runtime behavior for message-passing logic.

Running End-to-End (Playwright) Tests

E2E tests launch a built web application and drive it through a real Chromium browser.

First-time setup:

npx playwright install chromium

Then run:

npm run test:e2e

The script builds the app (npm run build), serves it with vite preview, and executes Playwright against the running instance. These smoke tests validate the complete integration of frontend, backend, and worker layers.

Running All Tests: The CI Command

To replicate the full Continuous Integration pipeline locally:

npm run ci

This executes:

• Linting
• Production build
• Frontend tests with coverage
• Worker type-checks and tests
• Backend tests with coverage
• Rust cargo check for the Tauri desktop shell

The ci script in package.json lines 28-30 defines the exact sequence that must pass before PR merge.

Complete Quick-Start Commands

# Full setup

git clone https://github.com/opengeos/GeoLibre.git
cd GeoLibre
npm install
pip install -e "backend/geolibre_server[test]"

# Individual test layers

npm run test:frontend   # TypeScript/UI tests

npm run test:backend    # Python FastAPI tests  

npm run test:worker     # Web Worker tests

npm run test:e2e        # Playwright browser tests

# Everything (CI equivalent)

npm run ci

Coverage and Quality Gates

GeoLibre enforces quality standards through automated checks:

• Frontend coverage: Validated by scripts/coverage-check.mjs against thresholds
• Backend coverage: pytest fails if below 55% line coverage
• Worker type safety: TypeScript strict mode checking before test execution

If you encounter frontend coverage failures, the CLAUDE.md documentation advises testing leaf modules to avoid transitive import bloat from the plugin registry.

Summary

• Four test layers cover GeoLibre's full stack: frontend (Node/TypeScript), backend (Python/pytest), workers (TypeScript/Node), and e2e (Playwright)
• npm scripts in package.json provide the canonical entry points: test:frontend, test:backend, test:worker, test:e2e
• Python extras [test] are required for backend coverage and geospatial dependencies
• CI replication uses npm run ci to validate all layers before submission

Frequently Asked Questions

Do I need Python installed to run frontend-only tests?

No. The npm run test:frontend command executes purely in Node.js with tsx compilation. Python is only required when running npm run test:backend or the full npm run ci pipeline.

Why does npm run test:backend fail with import errors?

The backend tests require geospatial libraries (geopandas, rasterio) installed through the [test] extras. Run pip install -e "backend/geolibre_server[test]" to resolve missing dependencies as documented in CLAUDE.md.

Can I run a single test file instead of the full suite?

For frontend tests, use Node's test runner directly: node --import tsx --test tests/wasm-convert.test.ts. For backend tests, use pytest's path filtering: python -m pytest backend/geolibre_server/tests/test_specific.py.

What does npm run ci include that individual test commands don't?

The CI command adds linting, production build verification, Rust cargo checks for the Tauri shell, and enforces all coverage thresholds simultaneously. Individual test commands run faster but skip these quality gates.

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