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

> Learn how to run tests for pdf-inspector with Cargo testing. Execute unit, integration, and OCR-specific tests easily using simple commands.

- Repository: [Firecrawl/pdf-inspector](https://github.com/firecrawl/pdf-inspector)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`](https://github.com/firecrawl/pdf-inspector/blob/main/tests/integration_tests.rs) and other files in the `tests/` directory
- **OCR-specific tests** – Gated behind the optional `ocr` feature flag in [`Cargo.toml`](https://github.com/firecrawl/pdf-inspector/blob/main/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:

```bash
cargo test

```

This executes all unit tests (defined inline with `#[cfg(test)]`) and integration tests from [`tests/integration_tests.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/tests/integration_tests.rs). According to the project's [`AGENTS.md`](https://github.com/firecrawl/pdf-inspector/blob/main/AGENTS.md) documentation and the CI workflow defined in [`.github/workflows/ci.yml`](https://github.com/firecrawl/pdf-inspector/blob/main/.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:

```bash
cargo test --test integration_tests

```

The integration test file resides at [`tests/integration_tests.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/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:

```bash
cargo test --features ocr

```

The CI pipeline invokes this variant for OCR-specific test jobs ([`.github/workflows/ci.yml`](https://github.com/firecrawl/pdf-inspector/blob/main/.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:

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

```bash
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`](https://github.com/firecrawl/pdf-inspector/blob/main/Cargo.toml) | Declares the `ocr` optional feature and lists test dependencies like `tokio-test` or `pretty_assertions` |
| [`tests/integration_tests.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/tests/integration_tests.rs) | Contains integration-level test cases exercising the public API |
| [`tests/ocr_tests.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/tests/ocr_tests.rs) | Houses tests requiring the full OCR runtime stack |
| [`.github/workflows/ci.yml`](https://github.com/firecrawl/pdf-inspector/blob/main/.github/workflows/ci.yml) | Documents exact test commands used in CI, including feature flag combinations |
| [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) | Exposes the public API under test; contains inline unit tests |
| [`rust-toolchain.toml`](https://github.com/firecrawl/pdf-inspector/blob/main/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

```bash

# 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`](https://github.com/firecrawl/pdf-inspector/blob/main/.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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/Cargo.toml).

### How does CI validate OCR functionality?

The GitHub Actions workflow in [`.github/workflows/ci.yml`](https://github.com/firecrawl/pdf-inspector/blob/main/.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`.