Trait WithFixture

Source

pub trait WithFixture:
    Default
    + ExpandDatabase
    + SourceDatabase
    + 'static {
    // Provided methods
    fn with_single_file(ra_fixture: &str) -> (Self, EditionedFileId) { ... }
    fn with_many_files(ra_fixture: &str) -> (Self, Vec<EditionedFileId>) { ... }
    fn with_files(ra_fixture: &str) -> Self { ... }
    fn with_files_extra_proc_macros(
        ra_fixture: &str,
        proc_macros: Vec<(String, ProcMacro)>,
    ) -> Self { ... }
    fn with_position(ra_fixture: &str) -> (Self, FilePosition) { ... }
    fn with_range(ra_fixture: &str) -> (Self, FileRange) { ... }
    fn with_range_or_offset(
        ra_fixture: &str,
    ) -> (Self, EditionedFileId, RangeOrOffset) { ... }
    fn test_crate(&self) -> Crate { ... }
}

Expand description

A trait for setting up test databases from fixture strings.

Fixtures are strings containing Rust source code with optional metadata that describe a project setup. This is the primary way to write tests for rust-analyzer without having to depend on the entire sysroot.

§Fixture Syntax

§Basic Structure

A fixture without metadata is parsed into a single source file (/main.rs). Metadata is added after a //- comment prefix.

//- /main.rs
fn main() {
    println!("Hello");
}

Note that the fixture syntax is optional and can be omitted if the test only requires a simple single file.

§File Metadata

Each file can have the following metadata after //-:

Path (required): Must start with /, e.g., /main.rs, /lib.rs, /foo/bar.rs
crate:<name>: Defines a new crate with this file as its root
- Optional version: crate:foo@0.1.0,https://example.com/repo.git
deps:<crate1>,<crate2>: Dependencies (requires crate:)
extern-prelude:<crate1>,<crate2>: Limits extern prelude to specified crates
edition:<year>: Rust edition (2015, 2018, 2021, 2024). Defaults to current.
cfg:<key>=<value>,<flag>: Configuration options, e.g., cfg:test,feature="foo"
env:<KEY>=<value>: Environment variables
crate-attr:<attr>: Crate-level attributes, e.g., crate-attr:no_std
new_source_root:local|library: Starts a new source root
library: Marks crate as external library (not workspace member)

§Global Meta (must appear at the top, in order)

//- toolchain: nightly|stable: Sets the Rust toolchain (default: stable)
//- target_data_layout: <layout>: LLVM data layout string
//- target_arch: <arch>: Target architecture (default: x86_64)
//- proc_macros: <name1>,<name2>: Enables predefined test proc macros
//- minicore: <flag1>, <flag2>: Includes subset of libcore

§Cursor Markers

Use $0 to mark cursor position(s) in the fixture:

Single $0: marks a position (use with with_position)
Two $0 markers: marks a range (use with with_range)
Escape as \$0 if you need a literal $0

§Examples

§Single file with cursor position

r#"
fn main() {
    let x$0 = 42;
}
"#

§Multiple crates with dependencies

r#"
//- /main.rs crate:main deps:helper
use helper::greet;
fn main() { greet(); }

//- /lib.rs crate:helper
pub fn greet() {}
"#

§Using minicore for lang items

r#"
//- minicore: option, result, iterator
//- /main.rs
fn foo() -> Option<i32> { Some(42) }
"#

The available minicore flags are listed at the top of crates\test-utils\src\minicore.rs.

§Using test proc macros

r#"
//- proc_macros: identity, mirror
//- /main.rs crate:main deps:proc_macros
use proc_macros::identity;

#[identity]
fn foo() {}
"#

Available proc macros: identity (attr), DeriveIdentity (derive), input_replace (attr), mirror (bang), shorten (bang)