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

> Learn how to run GeoLibre's tsx frontend and pytest backend test suites. This guide explains the testing frameworks and execution process for the opengeos/GeoLibre repository.

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

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/.test.ts) or [`.test.tsx`](https://github.com/opengeos/GeoLibre/blob/main/.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.

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

```bash
npm run test:frontend

```

This invokes `node --test` with the `tsx` loader across all files matching `tests/*.test.ts`. In [`package.json`](https://github.com/opengeos/GeoLibre/blob/main/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):

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

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

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

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

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

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

```bash
npx playwright install chromium

```

### E2E Test Customization

Pass additional flags through npm's argument forwarding:

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

```

The E2E test specifications reside in the `e2e/` directory, with [`record-video.spec.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/CLAUDE.md)** — Central reference document defining all repository commands including precise test script flags
- **[`tests/expressions.test.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/CLAUDE.md) in the repository root for the specific values and any per-directory overrides.