# toTextSnapshot (/docs/matchers/to-text-snapshot)



Signature [#signature]

```ts
toTextSnapshot(options?: SnapTextOptions): Promise<void>
```

Description [#description]

Converts the received value to a string and writes it to a snapshot file. On subsequent runs
the file content is diffed — the test fails if it differs.

Value coercion:

* `string` — written as-is.
* `Date` — converted to ISO 8601 string.
* Anything else — converted via `String()`, then slugified to lowercase.

No filters or redactions are applied. Use `toJsonSnapshot` if you need those.

Options [#options]

```ts
type SnapTextOptions = {
  dir?: string;
  name?: string;
  fileExtension?: string;
  args?: any[];
};
```

| Option          | Default           | Description                                        |
| --------------- | ----------------- | -------------------------------------------------- |
| `dir`           | `"./snapshots"`   | Directory relative to the test file                |
| `name`          | current test name | Slug used as the base filename                     |
| `fileExtension` | none              | Extension appended to the file                     |
| `args`          | `[]`              | Extra segments to distinguish parametric snapshots |

Examples [#examples]

Basic usage [#basic-usage]

```ts
test("user greeting", async () => {
  const greeting = buildGreeting({ name: "Alice" });
  await expect(greeting).toTextSnapshot();
  // writes: ./snapshots/user-greeting
});
```

With file extension [#with-file-extension]

```ts
test("html output", async () => {
  const html = renderPage();
  await expect(html).toTextSnapshot({ fileExtension: "html" });
  // writes: ./snapshots/html-output.html
});
```

Parameterized snapshots [#parameterized-snapshots]

```ts
test.each(["en", "fr", "de"])("greeting %s", async (locale) => {
  const greeting = buildGreeting({ locale });
  await expect(greeting).toTextSnapshot({ args: [locale] });
  // writes: ./snapshots/greeting-en
  // writes: ./snapshots/greeting-fr
  // writes: ./snapshots/greeting-de
});
```

Custom output directory [#custom-output-directory]

```ts
test("banner text", async () => {
  await expect(banner).toTextSnapshot({ dir: "./__text_snapshots__" });
});
```