home / skills / redisearch / redisearch / rust-tests-guidelines

rust-tests-guidelines skill

safe

This skill provides Rust test-writing guidelines, emphasizing public API testing, property-based techniques, and readable, reusable test scaffolds.

npx playbooks add skill redisearch/redisearch --skill rust-tests-guidelines

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.4 KB

---
name: rust-tests-guidelines
description: Guidelines for writing Rust tests.
---

# Guidelines for Writing Rust Tests

Guidelines for writing new tests for Rust code.

## Guidelines

1. Test against the public API of the code under test.
2. Test private APIs if and only if the private component is highly complex and difficult to test through the public API.
3. Use `insta` whenever you are testing output that is difficult to predict or compare.
4. Where appropriate, use `proptest` to add property-based tests for key invariants.
5. Testing code should be written with the same care reserved to production code.
   Avoid unnecessary duplication, introduce helpers to reduce boilerplate and ensure readability.
   The intent of a test should be obvious or, if not possible, clearly documented.
6. Do not reference exact line numbers in comments, as they may change over time.

## Code organization

1. Put tests under the `tests` directory of the relevant crate if they don't rely on private APIs.
2. The `tests` directory should be organized as a crate, with a `main.rs` file and all tests in modules. 
   Refer to the `trie_rs/tests` directory as an example.
3. If the test *must* rely on private APIs, co-locate them with the code they test, using a `#[cfg(test)]` module.

## Dealing with extern C symbols

Check out [CONTRIBUTING.md](../../src/redisearch_rs/CONTRIBUTING.md) for instructions on how to deal with
undefined C symbols in Rust tests.

Overview

This skill provides concise, practical guidelines for writing Rust tests in a system that interacts with external C symbols and implements complex search and indexing logic. It focuses on maintaining test quality, clear organization, and appropriate use of testing libraries to ensure reliable, maintainable test suites. The rules emphasize testing through public interfaces while allowing exceptions for highly complex private components.

How this skill works

It prescribes testing strategies, test placement, and tooling choices. Tests should exercise public APIs by default, use snapshot testing for hard-to-predict output, and apply property-based testing for invariants. For code that must interact with private internals or undefined C symbols, follow the project’s contribution guidance for safely co-locating and running those tests.

When to use it

When adding new features that expose behavior through the public API.
When a private component is highly complex and cannot be fully exercised through public calls.
When output formatting or structure is fragile and hard to assert precisely (use snapshot testing).
When core invariants or edge-case behavior should hold across many inputs (use property-based tests).
When tests must integrate with external C symbols or native code during execution.

Best practices

Prefer testing via the public API; keep tests focused on observable behavior, not implementation.
Introduce helpers to remove boilerplate and make test intent obvious; write tests with production-quality care.
Use insta (snapshot testing) for outputs that are difficult to compare deterministically.
Use proptest to cover broad input spaces and assert invariants instead of enumerating cases.
Organize tests under a dedicated tests crate when they don’t rely on private items; co-locate only when private access is required.
Avoid fragile comments such as exact line numbers; document non-obvious test intent instead.

Example use cases

Verifying that the public query API returns expected documents and scores after indexing.
Snapshot-testing serialized query plans, logs, or user-facing error messages that vary across environments.
Property-testing tokenization and normalization functions to ensure invariants over many input strings.
Co-locating unit tests that need access to private helpers used in the inverted-index implementation.
Writing integration tests that exercise vector similarity search and aggregation pipelines via the public client surface.

FAQ

When should I test private functions directly?

Only when the private component is complex and cannot be effectively exercised through the public API; otherwise prefer public-facing tests.

Which libraries are recommended for non-deterministic outputs or broad input coverage?

Use insta for snapshot-style comparisons and proptest for property-based testing of invariants.