From 9eea67ce6eddbf56856e0aa9dca655f971ebd4f0 Mon Sep 17 00:00:00 2001 From: David Anthoff Date: Tue, 25 Aug 2026 15:10:29 -0700 Subject: [PATCH] Document what a test item can import MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `@testitem` docstring documents `default_imports` and is the only statement of the macro's contract, but it never said what *else* is importable — so the question it most often has to answer, "why can't my test item `using Foo`?", was unanswered here and everywhere else. A test item can import the package's test target and nothing more: its `test/Project.toml`, or its own `[deps]` plus the `[targets]` `test` names resolved through `[extras]`/`[weakdeps]`, plus the package and the standard library. That is one target per package — a `Project.toml` deeper in the tree adds nothing, which is the misunderstanding behind TestItemControllers.jl#97 — and a `@testmodule` or `@testsnippet` is subject to the same limit. Co-Authored-By: Claude Opus 5 --- src/TestItems.jl | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/TestItems.jl b/src/TestItems.jl index 13e0604..18d7d86 100644 --- a/src/TestItems.jl +++ b/src/TestItems.jl @@ -28,6 +28,23 @@ to share setup code between test items. the environment of the process the tests actually run in, not the one that discovered them. +## What a test item can import + +A test item runs in the same environment `Pkg.test` would build for the package that owns +the file, so what it can `using` is the package's **test target** and nothing else: + +- the package's `test/Project.toml`, if it has one; otherwise +- the package's own `[deps]`, plus the names its `[targets]` `test` list names, each + declared in `[extras]` or `[weakdeps]`; + +plus the package itself, and the standard library. That is a single target per package — +Julia has no notion of per-directory test dependencies, so a `Project.toml` sitting deeper +in the tree does not add any. A `@testmodule` or `@testsnippet` is subject to the same +limit, since it is evaluated in the same environment. + +The runner that executes the test item decides which *versions* those resolve to, and +`ArgumentError: Package Foo not found in current path` means `Foo` is not in the target. + ## Examples ```julia