denoland / denoland/std

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

Open
#7,208 3 comments 2 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.