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

> Easily run GeoLibre unit tests for frontend, backend, workers, and e2e suites with simple npm commands. Follow our complete guide for all test layers.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-16

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/package.json) → `"test:frontend"` | Browser/UI code, store logic, WASM conversions |
| **Backend** | pytest | [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/package.json) → `"test:backend"` | FastAPI server, vector/raster utilities |
| **Workers** | Node.js + TypeScript checking | [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/package.json) → `"test:worker"` | Web Workers (viewer, collab, tiles, AI-proxy) |
| **End-to-End** | Playwright | [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/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**

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

```

2. **Install Node workspace dependencies**

```bash
npm install

```

This resolves all workspaces under `apps/*`, `packages/*`, and `workers/*` as defined in the root [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/package.json).

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

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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:

```bash
npm run test:frontend

```

Under the hood, this runs:

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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:

```bash
npm run test:backend

```

This forwards to:

```bash
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:

```bash
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:

```bash
npx playwright install chromium

```

Then run:

```bash
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:

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/package.json) lines 28-30 defines the exact sequence that must pass before PR merge.

## Complete Quick-Start Commands

```bash

# 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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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.