How to Run Invidious Tests: Complete Crystal Testing Guide

Run crystal spec from the repository root after installing dependencies with shards install and ensuring the DATABASE_URL environment variable points to a valid database.

Invidious, the privacy-focused YouTube frontend written in Crystal, uses the Spectator testing framework to ensure reliability. Running the test suite requires the Crystal toolchain, PostgreSQL or SQLite, and an understanding of the project's spec organization. This guide covers the exact commands and configuration needed to execute tests on the iv-org/invidious repository.

Prerequisites and Dependencies

Before running Invidious tests, install Crystal ≥ 1.0 on your system. Follow the official Crystal installation guide for your specific platform (Linux, macOS, or Windows).

Once Crystal is available, install the project's third-party libraries declared in shards.yml:

shards install

This command downloads Spectator and other dependencies required by the test suite.

Database Configuration

The Invidious test suite requires database connectivity. By default, tests connect to the database URL specified in the DATABASE_URL environment variable. If unset, the suite falls back to a local SQLite file as defined in src/invidious/config.cr.

For PostgreSQL testing, export the connection string before running tests:

export DATABASE_URL=postgres://user:pass@localhost/invidious_test

For SQLite testing, ensure the process has write permissions to the directory where the test database file will be created.

Executing the Test Suite

With dependencies installed and the database configured, run the complete test suite using Crystal's built-in spec runner:

crystal spec

This command recursively discovers every *_spec.cr file under the spec/ directory and executes them using the Spectator framework. The runner automatically loads spec/spec_helper.cr before each spec file, configuring test randomization and failure handling.

Verify your Crystal installation before running tests:

crystal --version

Test Organization and Structure

Understanding the spec directory layout helps when targeting specific test categories or debugging failures.

Unit Tests

Unit tests for core components like video extractors and helper utilities reside in spec/invidious/. For example, video extraction logic is tested in spec/invidious/videos/regular_videos_extract_spec.cr using Spectator's DSL methods (describe, it, expect).

Integration Tests

HTTP server integration tests, including static asset handling and routing verification, are located in spec/http_server/handlers/ such as spec/http_server/handlers/static_assets_handler_spec.cr. These specs verify the Kemal-based server's behavior end-to-end.

Configuration Files

The spec/spec_helper.cr file initializes Spectator and loads the main application code, making it the entry point for all test configurations. According to the iv-org/invidious source code, this global helper configures the testing environment and is automatically required by the Crystal runner.

Summary

• Install Crystal ≥ 1.0 and run shards install to fetch Spectator and dependencies declared in shards.yml.
• Configure the DATABASE_URL environment variable for PostgreSQL or rely on the SQLite fallback defined in src/invidious/config.cr.
• Execute crystal spec from the repository root to run all specs in the spec/ directory.
• Unit tests live in spec/invidious/ while HTTP integration tests are in spec/http_server/handlers/.
• The spec/spec_helper.cr file automatically configures the Spectator framework for each test run.

Frequently Asked Questions

Do I need PostgreSQL to run Invidious tests?

No. While production Invidious instances typically use PostgreSQL, the test suite can run against SQLite if you omit the DATABASE_URL environment variable. The configuration logic in src/invidious/config.cr automatically falls back to a local SQLite database file, making it possible to run basic tests without setting up a PostgreSQL server.

What testing framework does Invidious use?

Invidious uses Spectator, a Crystal testing framework that provides a DSL similar to RSpec. The framework is declared as a dependency in shards.yml and supports behaviors like describe, it, and expect blocks for writing expressive specifications.

How do I run a specific test file instead of the entire suite?

Target individual spec files by passing the file path to the Crystal command: crystal spec spec/invidious/videos/regular_videos_extract_spec.cr. This executes only the tests defined in that specific file while still loading spec/spec_helper.cr for configuration.

Where are the HTTP server tests located?

HTTP server integration tests, including handlers for static assets and routing logic, are stored in spec/http_server/handlers/. Files like spec/http_server/handlers/static_assets_handler_spec.cr contain integration tests that verify the web server behaves correctly under various request scenarios.

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