Developer Testing Guide

Developer Testing Guide#

This page describes how we use pytest markers and how to quarantine legacy tests while keeping visibility.

Marker conventions#

Use the following markers consistently:

  • @pytest.mark.integration For tests that exercise multiple layers together (for example writing/reading .pbm files plus mesh export).

  • @pytest.mark.slow For expensive tests that are valuable but too costly for the default unit test lane.

  • @pytest.mark.gui For tests that require an interactive display, browser, or rendering backend.

Keep unit tests (fast, deterministic, no external dependencies) unmarked.

Example usage:

import pytest

@pytest.mark.integration
def test_pbm_mesh_roundtrip(...):
    ...

@pytest.mark.slow
def test_large_spatial_encoding_stress(...):
    ...

@pytest.mark.gui
def test_interactive_plot(...):
    ...

How to run subsets#

Default fast lane:

pytest -m "not slow and not gui"

Include integration tests:

pytest -m "integration and not gui"

Run only GUI tests locally:

pytest -m "gui"

Run everything:

pytest

Quarantining legacy tests#

If a test is currently valuable for visibility but not ready for the default lane, quarantine it rather than deleting it.

Recommended approach:

  1. Keep the test under tests/ but mark it clearly (for example skip or a dedicated marker when introduced).

  2. Add a short reason and an issue/work item reference in the decorator or comment.

  3. Define an explicit exit condition (what must be implemented to unquarantine it).

Current quarantine candidates include:

  • tests/blockmodel/test_dxf_export.py (pending DXF workflow completion)

  • GUI-heavy cases in tests/blockmodel/test_toy_blockmodel.py

  • skipped structured-grid accessor case in tests/pyvista/test_accessor.py

Guideline#

Prefer a small number of focused test files by concern (ingest, indexing, visualization, integration) and avoid single monolithic files.