Testing Guide for ggblab

This document describes the structure of ggblab’s unit and integration tests, how to run them locally and on CI, coverage goals, and how to extend them.

Test Structure

  • Directory structure (excerpt)

    • tests/ (core unit tests)

      • test_file.py: Loading/saving by format (.ggb Base64, ZIP, JSON, XML), round-trip, edge cases

      • test_ggbapplet.py: GeoGebra lifecycle, validation, and cache management

      • __init__.py, conftest.py: Pytest configuration and shared fixtures

    • ggblab_extra/tests/ (advanced analysis)

      • test_parser.py: Dependency graph construction, root/leaf identification, topological sort, generation analysis

    • Root

      • pytest.ini: Coverage/marker/output configuration (covers both ggblab and ggblab_extra)

      • .github/workflows/tests.yml: Automated testing on GitHub Actions

Local Execution

Prerequisite: Activate virtual environment (Conda/venv)

pip install -e ".[dev]"
pip install pytest pytest-cov

# Run all tests
pytest

# Verbose output + coverage
pytest -v --cov=ggblab --cov-report=term-missing

# Specific file only
pytest tests/test_file.py -v
pytest tests/test_ggbapplet.py -v
pytest ggblab_extra/tests/test_parser.py -v

# Re-run failed tests only
pytest --lf

Generated artifacts:

  • htmlcov/ (HTML coverage report)

  • coverage.xml (coverage report for CI)

CI (GitHub Actions)

  • Workflow: .github/workflows/tests.yml

  • Targets: ubuntu-latest, macos-latest, windows-latest / Python 3.10–3.12

  • Execution steps:

    • Install dependencies (pip install -e ".[dev]")

    • Run tests with pytest + generate coverage

    • Upload to Codecov (optional)

Coverage Goals

  • v0.8.0: ≥50% (achieved primarily through construction, parser)

  • v0.9.0: ≥70% (add tests for comm, ggbapplet)

  • v1.0.0: ≥80% (integration tests/remaining edge cases)

Test Writing Guidelines

  • Single responsibility per test function (one test = one behavior)

  • Use fixtures (conftest.py) for test data generation and reuse

  • Prioritize edge cases (empty files, corrupted data, non-existent paths)

  • Provide meaningful error messages on failure (exception type/message)

  • Use round-trip testing when possible (load→save→load) for consistency validation

Representative Test Content (Overview)

  • tests/test_file.py

    • Loading Base64 .ggb / ZIP .ggb / JSON / XML

    • XML stripping to <construction> and normalization of scientific notation (e-1 → E-1)

    • Save behavior with/without Base64 (ZIP/plain XML)

    • Automatic filename generation (name_1.ggb, name_2.ggb)

    • Round-trip consistency validation

  • tests/test_ggbapplet.py

    • Singleton lifecycle, syntax/semantic validation, cache refresh, literal detection

  • ggblab_extra/tests/test_parser.py

    • Node/edge generation (dependencies)

    • Root/leaf identification

    • Topological sort/generation analysis (scope levels)

    • Transitive dependencies (A→AB→L→C→triangle, etc.)

Extension Plan (Proposed)

  • tests/test_comm.py: Mock tests for communication layer (IPython Comm + OOB socket)

  • tests/test_ggbapplet.py: Integration tests for GeoGebra API (init→function calls)

  • Playwright/Galata UI tests (separate repo/directory)

Troubleshooting

  • ImportError: ggblab.* not found

    • Verify that conftest.py adds project root to sys.path

    • Run pip install -e ".[dev]"

  • ZIP file-related failures on Windows

    • Be aware of path/line ending differences, pre-check with zipfile.is_zipfile()

  • Low coverage

    • Add more edge cases, write tests that exercise all branches

References

  • pytest.ini: Coverage and marker configuration

  • .github/workflows/tests.yml: CI execution conditions/environment

  • docs/ai_assessment.md: Technical assessment and test prioritization background