Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lissy93/adguardian-term/llms.txt

Use this file to discover all available pages before exploring further.

AdGuardian Term uses Cargo’s built-in test, clippy, and fmt tools for quality assurance. Tests are co-located with the source code in #[cfg(test)] modules — there is no separate test directory. Every quality check also runs automatically in CI on each pull request and push.

​
Running Tests

cargo test

# or via make:
make test
The make test target also ensures the project is compiled first (make build is listed as a prerequisite). The --all-features flag is used in CI to ensure feature-gated code paths are also exercised.

​
What Is Tested

The current test suite focuses on deserialization robustness — verifying that the application handles incomplete or unexpected API responses gracefully rather than panicking.

​
tests::empty_and_partial_json_decode_to_defaults

Location: src/fetch/fetch_query_log.rs This test verifies several important properties of the serde deserialization layer:
  • Empty JSON objects — QueryResponse, StatsResponse, and StatusResponse all derive #[serde(default)], so deserializing {} produces a fully populated struct with zero/false/empty defaults rather than a parse error.
  • Partial JSON — a StatsResponse with only some fields present (e.g. {"num_dns_queries": 5}) deserializes successfully, leaving all other fields at their defaults.
  • Blocked queries without an upstream field — when AdGuard Home blocks a query it does not include an upstream field in the query log entry. The test confirms that the Query struct deserializes this correctly to an empty string via #[serde(default)], rather than failing with a missing-field error.
#[cfg(test)]
mod tests {
    use super::*;
    use crate::fetch::fetch_stats::StatsResponse;
    use crate::fetch::fetch_status::StatusResponse;

    #[test]
    fn empty_and_partial_json_decode_to_defaults() {
        serde_json::from_str::<QueryResponse>("{}").unwrap();
        serde_json::from_str::<StatsResponse>("{}").unwrap();
        serde_json::from_str::<StatusResponse>("{}").unwrap();
        serde_json::from_str::<StatsResponse>(r#"{"num_dns_queries":5}"#).unwrap();

        // A blocked query has no `upstream`, default to empty
        let q = r#"{"cached":false,"client":"1.2.3.4","elapsedMs":"0.1",
          "question":{"class":"IN","name":"x.com","type":"A"},"reason":"x","time":"t"}"#;
        assert_eq!(serde_json::from_str::<Query>(q).unwrap().upstream, "");
    }
}

​
Linting

Clippy is configured to treat all warnings as errors (-D warnings), ensuring no latent issues accumulate in the codebase. 
cargo clippy -- -D warnings

# or:
make clippy
In CI, clippy is run against all targets and all features: 
cargo clippy --all-targets --all-features --locked -- -D warnings

​
Formatting

The project enforces a consistent code style using rustfmt. The --check flag makes the command exit with a non-zero code if any file would be reformatted, without actually modifying files — suitable for both local checks and CI. 
cargo fmt -- --check

# or:
make fmt
To reformat files in place locally, run cargo fmt without the -- --check flag.

​
Compilation Check

cargo check performs a fast compilation pass that resolves types and reports errors without producing a final binary. It is significantly faster than a full build and is useful for a quick feedback loop during development. 
cargo check --all-features

# or:
make check
In CI this is run with --all-features --locked to catch any feature-gated compilation issues.

​
Benchmarks

Benchmark tests can be executed with: 
cargo bench

# or:
make bench
The make bench target depends on make build, so the project is compiled before benchmarks run.

​
Generating Rust API Docs

Documentation is generated from Rustdoc comments using: 
cargo doc --no-deps --all-features

# or:
make doc
The --no-deps flag limits output to the project’s own crates, skipping dependency documentation. The generated HTML is written to target/doc/. The published version of the API docs is automatically built and deployed to GitHub Pages on each release: lissy93.github.io/AdGuardian-Term/adguardian In CI, docs are built with RUSTDOCFLAGS=-D warnings to catch broken intra-doc links and missing documentation.

​
CI Integration

All quality checks run automatically via GitHub Actions on every push and pull request, defined in .github/workflows/ci.yml. The workflow includes:
JobCommandWhen it runs
Formatcargo fmt --all --checkOn any Rust source change
Clippycargo clippy --all-targets --all-features --locked -- -D warningsOn any Rust source change
Testcargo test --all-features --lockedOn any Rust source change
Buildcargo build --release --lockedOn any Rust source change
Docscargo doc --no-deps --all-features --lockedOn any Rust source change
Workflow lintactionlint + zizmorOn any workflow file change
Secret scanTruffleHogOn pull requests
Dependency reviewGitHub dependency-review-actionOn PRs with dependency changes
The CI workflow uses path filtering to skip jobs that are unaffected by a given change. For example, Rust checks are skipped if only workflow files are modified, and vice versa. This keeps CI fast on documentation-only or tooling-only changes.
Running make with no target executes the full development cycle — clean → build → test → doc → run — in a single command. This is the quickest way to verify that everything compiles, tests pass, and docs build before opening a pull request.

Build docs developers (and LLMs) love

Get started for freeTalk to us