Home • Explore • Blog • CI
☰



rustc
2nd chunk of `src/tests/best-practices.md`
427ae9a043cd06a0835d5d919dba18e6e3a93f63cef20bc90000000100000ae3
> (if you `ls` a test directory and get a bunch of `issue-xxxxx` prefixes). We
> can link to the issue in a test comment.
>
> ```rs
> //! Check that `asm!` macro including nested macros that come from external
> //! crates do not lead to a codepoint boundary assertion ICE.
> //!
> //! Regression test for <https://github.com/rust-lang/rust/issues/123456>.
> ```
>
> tests are named only after issue numbers because its purpose is to track
> snippets from which issues no longer ICE/crash, and they would either be
> removed or converted into proper ui/other tests in the fix PRs.

## Test organization

- For most test suites, try to find a semantically meaningful subdirectory to
  home the test.
    - E.g. for an implementation of RFC 2093 specifically, we can group a
      collection of tests under `tests/ui/rfc-2093-infer-outlives/`. For the
      directory name, include what the RFC is about.
- For the [`run-make`] test suite, each `rmake.rs` must be contained within an
  immediate subdirectory under `tests/run-make/`. Further nesting is not
  presently supported. Avoid including issue number in the directory name too,
  include that info in a comment inside `rmake.rs`.

## Test descriptions

To help other contributors understand what the test is about if their changes
lead to the test failing, we should make sure a test has sufficient docs about
its intent/purpose, links to relevant context (incl. issue numbers or other
discussions) and possibly relevant resources (e.g. can be helpful to link to
Win32 APIs for specific behavior).

**Synopsis of a test with good comments**

```rust,ignore
//! Brief summary of what the test is exercising.
//! Example: Regression test for #123456: make sure coverage attribute don't ICE
//!     when applied to non-items.
//!
//! Optional: Remarks on related tests/issues, external APIs/tools, crash
//!     mechanism, how it's fixed, FIXMEs, limitations, etc.
//! Example: This test is like `tests/attrs/linkage.rs`, but this test is
//!     specifically checking `#[coverage]` which exercises a different code
//!     path. The ICE was triggered during attribute validation when we tried
//!     to construct a `def_path_str` but only emitted the diagnostic when the
//!     platform is windows, causing an ICE on unix.
//!
//! Links to relevant issues and discussions. Examples below:
//! Regression test for <https://github.com/rust-lang/rust/issues/123456>.
//! See also <https://github.com/rust-lang/rust/issues/101345>.
//! See discussion at <https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler/topic/123456-example-topic>.
//! See [`clone(2)`].
//!
//! [`clone(2)`]: https://man7.org/linux/man-pages/man2/clone.2.html

//@ ignore-windows
// Reason: (why is this test ignored for windows? why not specifically
Title: Test Organization and Descriptions
Summary
This section focuses on the importance of well-organized tests within meaningful subdirectories. It highlights the necessity of clear test descriptions that include summaries of the test's purpose, links to relevant issues or discussions, and any platform-specific considerations (e.g., why a test is ignored on Windows). The aim is to provide sufficient context for contributors to understand the test's intent, especially when debugging failures.