Proposal: deprecate @std/testing/bdd and @std/testing/snapshot in favor of built-ins
- Dominant language
- TypeScript
- Stars
- 3.6k
- Forks
- 681
- PR merge metrics
- No merged PRs in 30d
Description
## 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](https://deno.com/blog/v2.9#snapshot-testing)). 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.
Contributor guide
Assessment
This issue has not been assessed yet.