tests/testthat/README.md

In couplr: Optimal Pairing and Matching via Linear Assignment

Test Organization

This directory contains the test suite for the couplr package, organized into logical subdirectories for better maintainability.

Directory Structure

tests/testthat/
├── algorithms/          # Core assignment algorithm tests
│   ├── test-assignment-auction.R
│   ├── test-assignment-auction-gs.R
│   ├── test-assignment-auto.R
│   ├── test-assignment-csflow.R
│   ├── test-assignment-hk01.R
│   ├── test-assignment-hungarian.R
│   ├── test-assignment-jv.R
│   ├── test-assignment-ssap-bucket.R
│   ├── test-assignment-ssp.R
│   └── test-cycle-cancel.R
├── gabow-tarjan/        # Gabow-Tarjan solver tests
│   ├── test-gabow_tarjan_solver.R
│   └── test_gabow_tarjan_module[A-H].R
├── kbest/              # K-best assignment algorithm tests
│   ├── test-kbest-lawler.R
│   └── test-kbest-murty.R
├── api/                # Modern API layer tests
│   ├── test-assign.R
│   └── test-assignment.R
├── matching/           # High-level matching functionality
│   └── test-matching.R
├── utilities/          # Utility function tests
│   ├── test-line-metric.R
│   ├── test-pixel-morph.R
│   └── test-prepare-cost-matrix.R
└── regression/         # Performance and regression tests
    └── test-auction-hang.R

Test Categories

Algorithms (algorithms/)

Tests for the core linear assignment problem solvers: - JV (Jonker-Volgenant): Efficient auction-based algorithm - Hungarian: Classic Hungarian algorithm - Auction: Standard auction algorithm with various epsilon values - Auction-GS: Gauss-Seidel auction variant - SSP/SAP: Shortest augmenting path algorithms - CSFlow: Cost-scaling flow algorithm - HK01: Hopcroft-Karp for 0/1 matrices - Auto: Automatic algorithm selection based on problem characteristics - Cycle Cancel: Cycle cancellation min-cost flow algorithm

Gabow-Tarjan (gabow-tarjan/)

Tests for the Gabow-Tarjan 1-feasible complementary slackness algorithm: - High-level solver tests with complementary slackness verification - Modular component tests (modules A through H)

K-Best (kbest/)

Tests for finding the k-best assignments: - Lawler: Lawler's algorithm for k-best solutions - Murty: Murty's partitioning algorithm

API (api/)

Tests for the modern user-facing API: - lap_solve(): Main assignment function with matrix/data frame inputs - lap_solve_batch(): Batch processing for multiple problems - lap_solve_kbest(): K-best solutions interface - Grouped data operations with dplyr integration - Print methods and utilities

Matching (matching/)

High-level matching functionality for practical applications: - matchmaker(): Blocking and stratification - match_couples(): Optimal matching with constraints - greedy_couples(): Fast greedy matching strategies - Distance computation and caching - Balance diagnostics and covariate assessment - Join operations for matched data

Utilities (utilities/)

Supporting functions and domain-specific utilities: - Cost matrix preparation - Pixel morphing metrics - Line distance metrics

Regression (regression/)

Performance and regression tests: - Auction algorithm hang prevention - Timing guards for algorithm performance

Running Tests

All tests

devtools::test()
# or
testthat::test_dir("tests/testthat")

Specific category

testthat::test_dir("tests/testthat/algorithms")
testthat::test_dir("tests/testthat/matching")

Single file

testthat::test_file("tests/testthat/algorithms/test-assignment-jv.R")

Test Conventions

• All test files follow the test-*.R naming convention
• Tests use testthat expectations (expect_equal, expect_true, etc.)
• Expensive tests use skip_on_cran() to avoid CRAN timeouts
• Numerical comparisons use appropriate tolerance (typically 1e-8 to 1e-10)
• Cross-validation: algorithms are compared against each other for correctness
• Each test group validates:
• Correctness (optimal cost)
• Edge cases (NA, Inf, empty, rectangular matrices)
• Minimize/maximize duality
• Proper error handling

Notes

• testthat automatically discovers tests in subdirectories
• The directory structure does not affect test execution
• Tests can reference each other through the package namespace

couplr documentation built on Jan. 20, 2026, 5:07 p.m.