# toMarkdownSnapshot (/docs/matchers/to-markdown-snapshot)



Signature [#signature]

```ts
toMarkdownSnapshot(options?: SnapMarkdownOptions<T>): Promise<void>
```

Description [#description]

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

Before rendering, the value passes through the same **filters** and **redactions** pipeline
as `toJsonSnapshot`. The final Markdown is written via `toMatchFileSnapshot`.

Rendering rules [#rendering-rules]

| Input                     | Output                                           |
| ------------------------- | ------------------------------------------------ |
| Array of objects          | One row per element; columns = union of all keys |
| Single object             | One row; columns = object keys                   |
| Primitive / non-object    | Single-column table with header `value`          |
| `null` / `undefined` cell | Empty string                                     |
| Nested object cell        | `JSON.stringify(value)`                          |
| `Date` cell               | `.toISOString()`                                 |

Defaults applied automatically [#defaults-applied-automatically]

| Concern           | Default behaviour                                           |
| ----------------- | ----------------------------------------------------------- |
| `undefined` props | Removed by `UndefinedFilter`                                |
| `Date` values     | Replaced with `[Date_1]`, `[Date_2]`, … by `ValueRedaction` |

Options [#options]

```ts
type SnapMarkdownOptions<T> = {
  dir?: string;
  name?: string;
  fileExtension?: string;
  args?: any[];
  filters?: (Selector<T> | Filter<T>)[];
  redactions?: Redaction<T>[];
};
```

| 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 for parametric snapshots                               |
| `filters`       | `[new UndefinedFilter()]`                | Filters applied before rendering — see [Filters](/docs/filters)       |
| `redactions`    | `[new ValueRedaction(isDate, "[Date]")]` | Redactions applied after filters — see [Redactions](/docs/redactions) |

Examples [#examples]

Array of objects [#array-of-objects]

```ts
test("user list", async () => {
  const users = [
    { id: 1, name: "Alice", role: "admin" },
    { id: 2, name: "Bob", role: "viewer" },
  ];
  await expect(users).toMarkdownSnapshot();
});
```

Snapshot file:

```md
| id  | name  | role   |
| --- | ----- | ------ |
| 1   | Alice | admin  |
| 2   | Bob   | viewer |
```

Single object [#single-object]

```ts
test("config object", async () => {
  const config = { host: "localhost", port: 5432, ssl: true };
  await expect(config).toMarkdownSnapshot({ fileExtension: "md" });
});
```

Snapshot file:

```md
| host      | port | ssl  |
| --------- | ---- | ---- |
| localhost | 5432 | true |
```

With custom file extension [#with-custom-file-extension]

```ts
test("report", async () => {
  await expect(rows).toMarkdownSnapshot({ fileExtension: "md" });
  // writes: ./snapshots/report.md
});
```

Parameterized snapshots [#parameterized-snapshots]

```ts
test.each(["admin", "viewer"])("users with role %s", async (role) => {
  const users = await fetchUsersByRole(role);
  await expect(users).toMarkdownSnapshot({ args: [role] });
  // writes: ./snapshots/users-with-role-admin
  // writes: ./snapshots/users-with-role-viewer
});
```

Exclude sensitive columns [#exclude-sensitive-columns]

```ts
import { ExcludeFilter } from "vitest-snap";

test("public user list", async () => {
  await expect(users).toMarkdownSnapshot({
    filters: [new ExcludeFilter(".passwordHash")],
  });
});
```