Proposal: deprecate @std/testing/bdd and @std/testing/snapshot in favor of built-ins

[bartlomieju]

Summary

We propose deprecating the @std/testing/bdd and @std/testing/snapshot exports (plus @std/testing/unstable-bdd) in favor of functionality that is now built into the Deno test runner and the node:test module. The @std/testing/mock, @std/testing/time, and @std/testing/types exports are not affected.

Motivation

Both modules now have first-class equivalents in the runtime:

• Snapshots: Deno 2.9 added a built-in t.assertSnapshot() on the test context (blog post). It uses the same file format and serializer as @std/testing/snapshot, so existing __snapshots__/*.snap files keep working. It supports serializer, name, dir/path, and mode options, and snapshots are updated with deno test --update-snapshots (-u), which also prunes stale entries. node:test additionally provides t.assert.snapshot() and t.assert.fileSnapshot() for code that also runs on Node.js.
• BDD: node:test's describe/it/test (including .only, .skip, .todo and the before/beforeEach/after/afterEach hooks) are supported first-class by deno test. For the flat style, Deno.test gained Deno.test.beforeAll/beforeEach/afterEach/afterAll hooks in Deno 2.5 and Deno.test.each() in Deno 2.9.

Keeping userland duplicates of built-in functionality adds maintenance burden and splits the ecosystem, so we'd like to point users at the built-ins going forward.

Migration

@std/testing API	Replacement	Since
assertSnapshot(t, value, opts)	await t.assertSnapshot(value, opts)	Deno 2.9
createAssertSnapshot(opts)	pass options to t.assertSnapshot() (or wrap it)	Deno 2.9
describe / it / test + hooks	node:test describe / it / test + hooks	Deno 1.36+
it.only / it.skip / it.ignore	node:test it.only / it.skip	—
describe.todo / it.todo / test.todo (unstable-bdd)	node:test .todo variants	—
flat-style hooks	Deno.test.beforeAll / beforeEach / afterEach / afterAll	Deno 2.5
configureGlobalSanitizers (unstable-bdd)	no direct equivalent; set sanitizer options per test via Deno.test options	—

Known gap: describe(...) accepts Deno.test options (sanitizeOps, sanitizeResources, permissions, ...) per suite; node:test suites don't. Code relying on per-suite options can migrate to the flat Deno.test style instead. The module docs will cover this.

Not (yet) included: @std/testing/unstable-snapshot

assertInlineSnapshot() has no built-in equivalent: neither the Deno test runner nor node:test supports inline snapshots today (upstream feature request: nodejs/node#59231). We'll hold off deprecating this export until an inline-snapshot built-in exists.

Plan

1. Land deprecation PRs (deprecation(testing): snapshot, deprecation(testing): bdd) adding @deprecated JSDoc tags to all affected exported symbols, with removal slated for @std/testing@2.0.0, and rewriting the module docs into migration guides.
2. Migrate internal usage in this repo (expect docs/tests, tooling) to the built-ins.
3. Update the docs.deno.com tutorials that currently teach @std/testing/bdd and @std/testing/snapshot to teach the built-ins instead.
4. At a later, yet-undecided point, release @std/testing@2.0.0 with the deprecated exports removed. The deprecated APIs keep working for the entire 1.x line.

Feedback welcome — especially if you rely on APIs from these modules that the built-ins don't cover.

[lowlighter]

It's not directly related to the @std/testing package, but here's minor inconveniences I have with the current builtin Deno.test:

• Deno.test steps are necessarily async which cause a lot of visual pollution when you have a lot of one-liner steps since you need to await them all (not awaiting them necessarily throws telling that previous step started before the completion of current one)
• The Deno.test.ignore should be aliased with Deno.test.skip (bdd does that actually)
  • skip is pretty common name and ignore seems the outlier one, most test framework use skip i believe
  • skip is 4 characters which match as a nice counterpart for only which is also 4 characters

[bartlomieju]

@lowlighter can you open an issue in Deno repo for these?

[tomas-zijdemans]

I support this