How to Run Tests for pdf-inspector: A Complete Guide to Cargo Testing

Run cargo test to execute all unit and integration tests, or cargo test --features ocr to include OCR-specific tests that require additional dependencies.

The pdf-inspector project by Firecrawl provides a Rust-based toolkit for analyzing and extracting information from PDF documents. Whether you're contributing code or verifying functionality on your local machine, understanding how to run the test suite is essential for maintaining code quality and catching regressions early.

Understanding the Test Structure

The pdf-inspector repository organizes its test coverage across three distinct layers, as implemented in firecrawl/pdf-inspector:

• Unit tests – Embedded directly in source files via #[cfg(test)] blocks throughout the codebase
• Integration tests – Located in tests/integration_tests.rs and other files in the tests/ directory
• OCR-specific tests – Gated behind the optional ocr feature flag in Cargo.toml

This structure allows contributors to run targeted test subsets based on their current work and available dependencies.

Basic Test Execution

Run All Standard Tests

The simplest way to verify the project is with Cargo's default test command:

cargo test

This executes all unit tests (defined inline with #[cfg(test)]) and integration tests from tests/integration_tests.rs. According to the project's AGENTS.md documentation and the CI workflow defined in .github/workflows/ci.yml (line 43), this is the baseline verification step used in continuous integration.

Run a Specific Integration Test File

To limit execution to a particular integration test file:

cargo test --test integration_tests

The integration test file resides at tests/integration_tests.rs and contains the bulk of the repository's integration-level test cases.

Running OCR-Enabled Tests

Run All Tests Including OCR

Some pdf-inspector functionality requires optical character recognition capabilities. Enable these tests with the ocr feature flag:

cargo test --features ocr

The CI pipeline invokes this variant for OCR-specific test jobs (.github/workflows/ci.yml, line 142). This command runs the full standard suite plus any tests marked with #[cfg(feature = "ocr")].

Run Only OCR Tests

To isolate just the OCR test suite with verbose output:

cargo test --features ocr --test ocr_tests -- --nocapture

This pattern appears in the CI workflow for the dedicated "ocr_tests" job (.github/workflows/ci.yml, line 252). The --nocapture flag ensures test output displays immediately rather than being buffered.

Environment Setup for OCR Testing

Before running OCR-enabled tests, you may need to configure library paths for the OCR runtime:

Variable	Purpose
PDFIUM_LIB_PATH	Path to the PDFium library for PDF rendering
ORT_DYLIB_PATH	Path to the ONNX Runtime dynamic library for ML inference

Export these variables before invoking Cargo if your OCR dependencies reside in non-standard locations:

export PDFIUM_LIB_PATH=/path/to/pdfium
export ORT_DYLIB_PATH=/path/to/onnxruntime
cargo test --features ocr

Key Files for Test Configuration

File	Role in Testing
Cargo.toml	Declares the ocr optional feature and lists test dependencies like tokio-test or pretty_assertions
tests/integration_tests.rs	Contains integration-level test cases exercising the public API
tests/ocr_tests.rs	Houses tests requiring the full OCR runtime stack
.github/workflows/ci.yml	Documents exact test commands used in CI, including feature flag combinations
src/lib.rs	Exposes the public API under test; contains inline unit tests
rust-toolchain.toml	Pins the required Rust version for reproducible builds

Consult these files directly in the repository to understand test organization and dependency requirements.

Common Test Commands Reference

# Quick verification (no OCR)

cargo test

# Full verification with OCR capabilities

cargo test --features ocr

# Debug a failing OCR test with output

cargo test --features ocr --test ocr_tests -- --nocapture

# Run specific integration scenario

cargo test --test integration_tests extract_text_from_scanned_pdf

# Check without running (compile test code only)

cargo test --no-run

Summary

• Use cargo test for standard development workflows covering unit and integration tests
• Add --features ocr when testing OCR-dependent functionality or verifying full coverage
• Reference .github/workflows/ci.yml for the authoritative test commands used in production CI
• Set PDFIUM_LIB_PATH and ORT_DYLIB_PATH before OCR testing if libraries are installed outside system paths
• Target specific test files with --test integration_tests or --test ocr_tests for faster feedback loops

Frequently Asked Questions

What Rust version does pdf-inspector require?

The repository includes a rust-toolchain.toml file that pins the exact Rust toolchain version. Cargo automatically uses this version when running tests, ensuring consistency across development environments and CI.

Why do some tests fail without the ocr feature?

Tests in tests/ocr_tests.rs and某些 inline tests gated with #[cfg(feature = "ocr")] require additional native dependencies (PDFium, ONNX Runtime) that are not bundled with the core library. These are intentionally optional to keep the base build lightweight.

Can I run tests without installing OCR libraries?

Yes—cargo test runs the full standard suite without any OCR dependencies. Only commands explicitly including --features ocr require the additional libraries, as enforced by the feature flag system in Cargo.toml.

How does CI validate OCR functionality?

The GitHub Actions workflow in .github/workflows/ci.yml defines separate jobs: one for standard tests (line 43) and dedicated jobs for OCR tests (lines 142, 252) that install required dependencies before invoking cargo test --features ocr.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}