The dart-lang/test repository is eight packages, and most teams only need one

One user-facing library and a set of parts

The repository describes itself as the home of package:test, the standard testing library for Dart and Flutter. The welcome note is direct about the boundaries: if you have questions about Dart testing, see the docs for package:test, and package:test_api and package:test_core are implementation details that are generally not user-facing.

That sentence is the most useful thing in the readme, because the package table below it lists eight packages and gives no hint about which ones you should touch. The six with issue links in the table (checks, fake_async, matcher, test, test_descriptor and test_process) are the ones the maintainers consider user-facing, while test_api and test_core have a pub badge but no issue link.

The split is by role. package:test is a full featured library for writing and running Dart tests across platforms. package:test_api is the user facing API for structuring Dart tests and checking expectations, so it is the layer a test author programs against, while test_core is a basic library for writing tests and running them on the VM, which is the engine underneath.

The other four are optional tools you pull in when your problem needs them. fake_async gives you fake asynchronous events such as timers and microtasks for deterministic testing, test_descriptor is an API for defining and verifying files and directory structures, and test_process handles test processes, starting them, validating stdout and stderr and checking the exit code.

checks versus matcher, and which one to write in

The expectation layer is where a new user has to make a decision, and the readme is clear that there are two libraries and that one of them is the newer one.

package:checks is described as a relatively new library for expressing test expectations. It is a more modern version of package:matcher, and it features a literate API. The word literate is doing specific work here, meaning the API is written to be read as documentation as much as to be called.

package:matcher is the older library, and its description is the traditional one: support for specifying test expectations via an extensible Matcher class, which also includes a number of built-in Matcher implementations for common cases.

So the division is between an extensible class-based matcher system and a newer framework for checking values against expectations and building custom expectations. The checks description mentions both halves, checking values against expectations and building custom expectations, which is a slightly different emphasis from matcher's built-in implementations for common cases.

The practical consequence for a new project is that you are choosing a dialect for every assertion you write, and the two are not the same. Nothing in the readme says matcher is going away, but the framing of checks as a more modern version is a signal about where the maintainers would put new effort.

The repository is a mono-repo, and the packages version independently

The layout of the repository explains the package table. There is a pkgs directory holding the packages, a tool directory, an integration_tests directory, and a mono_repo.yaml file describing the mono-repo setup. There is also a pubspec.yaml at the root, a CODEOWNERS file, a CONTRIBUTING guide, an analysis_options.yaml for the Dart analyzer, and a.github directory with the Dart CI workflow.

The important operational consequence is visible in the release history. The recent releases are not one version but three, published within about two minutes of each other: test_core v0.6.21 on 2026-10-08, test_api v0.7.15 on 2026-10-08, and test v1.33.0 on 2026-10-08.

So the packages are released in a coordinated batch, but each carries its own version line and its own number. The test package is at 1.33.0, the test_api package is at 0.7.15 and the test_core package is at 0.6.21, and they are not tied to the same minor number despite shipping together.

That matters for dependency resolution. When you depend on package:test you are pulling in a dependency graph that includes the api and core packages, and those have their own version constraints. A project that pins package:test to an exact version is pinning a graph, not a single artifact, and the release numbers here do not give you a simple way to reason about which combination goes with which.

The last push was on 2026-10-22, and the releases themselves are from 2026-10-08, so the branch is a little ahead of the published packages.

What the tooling around the packages tells you

The badges and configuration in the readme give a picture of how the project is maintained rather than of what it does.

There is a Dart CI workflow badge pointing at the dart.yml workflow, and an OpenSSF Scorecard badge from the security scorecards service, which points at the project on deps.dev. The Scorecard badge is a supply chain signal, and it is a reasonable one for a package that sits in the dependency tree of most Dart and Flutter applications.

The repository also has a CODEOWNERS file, which is how a project of this size assigns review responsibility per directory, and a CONTRIBUTING guide, which is the document that tells a first-time contributor how the mono-repo works. There is a .gitattributes file and a .gitignore, and the analysis_options.yaml at the root suggests the analyzer configuration is shared across the packages rather than duplicated per package.

The homepage is the package page on pub.dev, which is where Dart developers actually find a package, and the table in the readme links each package to its own pub.dev page. The issue links in the table are filtered by package label, so each package has its own issue stream under the same repository, which is the usual arrangement for a Dart mono-repo and means a bug in the fake_async package does not land in the queue of the test runner.

Choosing between the optional packages

The four optional packages exist for specific problems, and each description names a different kind of difficulty.

fake_async is for determinism. It provides fake asynchronous events such as timers and microtasks, which means a test that depends on a timer firing can control when it fires rather than sleeping and hoping. The problem it solves is a test that passes on a fast machine and fails on a slow one.

test_descriptor is for file and directory fixtures. It is an API for defining and verifying files and directory structures, which is the piece you reach for when a test needs to assert that a tree of files exists with particular contents, rather than checking one file at a time.

test_process is for anything that shells out. Its description is a list of three capabilities: starting a process, validating stdout and stderr, and checking the exit code. That is exactly the set of assertions you need when the unit under test is a command line tool, and it is a gap the core library does not fill.

What none of the readme gives you is guidance on when to reach for which. The descriptions are one line each, and there is no tutorial or example in the readme itself, which points you at the package docs instead. The readme's own contribution is the structure, the package boundaries and the pointers, and the per-package documentation is where the detail lives.

Editorial conclusion

Adopt package:test if you write Dart or Flutter and want the standard runner and expectation library, and read the difference between package:matcher and package:checks before you choose which one to write assertions in. Do not reach for the other packages in the repository, because package:test_api and package:test_core are described as implementation details that are generally not user-facing. Before you depend on it, check three things: which expectation library your new tests should use, since checks is the more modern of the two and matcher is the older, whether you need test_descriptor or test_process for your fixture and subprocess work, and how you pin versions, since the packages move on separate version lines and the test package is currently at 1.33.0.

Frequently asked questions

Official sources

1. dart-lang/test on GitHub
2. Issues
3. Project website
4. README
5. Releases