docs: improve snapshot docs

docs/.vitepress/components/FeaturesList.vue

@@ -12,7 +12,11 @@
     <ListItem>ESM first, top level await</ListItem>
     <ListItem>Workers multi-threading via <a target="_blank" href="https://github.com/Aslemammad/tinypool" rel="noopener noreferrer">tinypool</a></ListItem>
     <ListItem>Filtering, timeouts, concurrent for suite and tests</ListItem>
-    <ListItem><a target="_blank" href="https://jestjs.io/docs/snapshot-testing" rel="noopener noreferrer">Jest Snapshot</a></ListItem>
+    <ListItem>
+      <a href="/guide/snapshot">
+        Jest-compatible Snapshot
+      </a>
+    </ListItem>
     <ListItem><a target="_blank" href="https://www.chaijs.com/" rel="noopener noreferrer">Chai</a> built-in for assertions + <a target="_blank" href="https://jestjs.io/docs/expect" rel="noopener noreferrer">Jest expect</a> compatible APIs</ListItem>
     <ListItem><a target="_blank" href="https://github.com/Aslemammad/tinyspy" rel="noopener noreferrer">Tinyspy</a> built-in for mocking</ListItem>
     <ListItem><a target="_blank" href="https://github.com/capricorn86/happy-dom" rel="noopener noreferrer">happy-dom</a> or <a target="_blank" href="https://github.com/jsdom/jsdom" rel="noopener noreferrer">jsdom</a> for DOM mocking</ListItem>

docs/.vitepress/components/ListItem.vue

@@ -16,8 +16,8 @@ function reset() {
 
 const color = computed(() => {
   return {
-    '--c-brand': state.value === 1
-      ? 'rgba(74,222,128,1)'
+    '--vp-c-brand': state.value === 1
+      ? '#66ba1c'
       : state.value === 2
         ? 'rgba(248, 113, 113)'
         : 'rgba(250, 204, 21)',

docs/.vitepress/config.ts

@@ -121,17 +121,20 @@ export default defineConfig({
               text: 'CLI',
               link: '/guide/cli',
             },
-            {
-              text: 'Mocking',
-              link: '/guide/mocking',
-            },
             {
               text: 'Test Filtering',
               link: '/guide/filtering',
             },
-
             {
-              text: 'In-source testing',
+              text: 'Snapshot',
+              link: '/guide/snapshot',
+            },
+            {
+              text: 'Mocking',
+              link: '/guide/mocking',
+            },
+            {
+              text: 'In-source Testing',
               link: '/guide/in-source',
             },
             {
@@ -142,10 +145,6 @@ export default defineConfig({
               text: 'Extending Matchers',
               link: '/guide/extending-matchers',
             },
-            {
-              text: 'Snapshot Serializer',
-              link: '/guide/snapshot-serializer',
-            },
             {
               text: 'IDE Integration',
               link: '/guide/ide',

docs/.vitepress/style/vars.css

@@ -4,13 +4,14 @@
 
 :root {
   --vp-c-accent: rgb(218, 180, 11);
-  --vp-c-brand: #61aa17;
+  --vp-c-brand: #6ab02c;
   --vp-c-brand-light: #9ac440;
   --vp-c-brand-lighter: #acd05c;
   --vp-c-brand-dark: #668d11;
   --vp-c-brand-darker: #52730d;
+  --vp-c-text-code: #bbeebb;
   --vp-code-block-bg: rgba(125,125,125,0.04);
-  --vp-c-green-light: rgb(18, 181, 157);
+  --vp-custom-block-tip-text: rgb(18, 181, 157);
   --vp-custom-block-tip-border: rgba(18, 181, 157, 0.5);
   --vp-custom-block-tip-bg: rgba(18, 181, 157, 0.1);
 }

docs/api/index.md

@@ -1380,7 +1380,7 @@ When you use `test` in the top level of file, they are collected as part of the
 
 - **Type:** `(plugin: PrettyFormatPlugin) => void`
 
-  This method adds custom serializers that are called when creating a snapshot. This is advanced feature - if you want to know more, please read a [guide on custom serializers](/guide/snapshot-serializer).
+  This method adds custom serializers that are called when creating a snapshot. This is advanced feature - if you want to know more, please read a [guide on custom serializers](/guide/snapshot#custom-serializer).
 
   If you are adding custom serializers, you should call this method inside [`setupFiles`](/config/#setupfiles). This will affect every snapshot.
 

docs/guide/cli.md

@@ -2,27 +2,39 @@
 
 ## Commands
 
-### `vitest watch`
+### `vitest`
+
+Start Vitest in the current directory. Will enter the watch mode in development environment and run mode in CI automatically.
+
+You can pass a addition argument as the filter of the tests files to run. For example:
+
+```bash
+vitest foobar
+```
 
-  Run all test suites but watch for changes and rerun tests when they change. Same as calling `vitest` without a command. In CI environments this command will fallback to `vitest run`
+Will run only the test file that contains `foobar` in their paths.
 
 ### `vitest run`
 
-  Perform a single run without watch mode.
+Perform a single run without watch mode.
+
+### `vitest watch`
+
+Run all test suites but watch for changes and rerun tests when they change. Same as calling `vitest` without a command. Will fallback to `vitest run` in CI.
 
 ### `vitest dev`
 
-  Run vitest in development mode.
+Alias to `vitest watch`.
 
 ### `vitest related`
 
-  Run only tests that cover a list of source files. Works with static lazy imports, but not the dynamic ones. All files should be relative to root folder.
+Run only tests that cover a list of source files. Works with static lazy imports, but not the dynamic ones. All files should be relative to root folder.
 
-  Useful to run with [`lint-staged`](https://github.com/okonet/lint-staged) or with your CI setup.
+Useful to run with [`lint-staged`](https://github.com/okonet/lint-staged) or with your CI setup.
 
-  ```bash
-  vitest related /src/index.ts /src/hello-world.js
-  ```
+```bash
+vitest related /src/index.ts /src/hello-world.js
+```
 
 ## Options
 

docs/guide/features.md

@@ -70,7 +70,18 @@ You can also use `.skip`, `.only`, and `.todo` with concurrent suites and tests.
 
 ## Snapshot
 
-[Jest Snapshot](https://jestjs.io/docs/snapshot-testing) support
+[Jest-compatible](https://jestjs.io/docs/snapshot-testing) snapshot support.
+
+```ts
+import { expect, it } from 'vitest'
+
+it('renders correctly', () => {
+  const result = render()
+  expect(result).toMatchSnapshot()
+})
+```
+
+Learn more at [Snapshot](/guide/snapshot)
 
 ## Chai and Jest expect compatibility
 

docs/guide/snapshot.md

@@ -0,0 +1,110 @@
+# Snapshot
+
+Snapshot tests are a very useful tool whenever you want to make sure the output of your functions not change unexpectedly.
+
+When using snapshot, Vitest will take a snapshot of the given value, then compares it to a reference snapshot file stored alongside the test. The test will fail if the two snapshots do not match: either the change is unexpected, or the reference snapshot needs to be updated to the new version of the result.
+
+## Use Snapshots
+
+To snapshoting a value, you can use the [`toMatchSnapshot()`](/api/#tomatchsnapshot) from `expect()` API:
+
+```ts
+import { expect, it } from 'vitest'
+
+it('toUpperCase', () => {
+  const result = toUpperCase('foobar')
+  expect(result).toMatchSnapshot()
+})
+```
+
+The first time this test is run, Vitest creates a snapshot file that looks like this:
+
+```js
+// Vitest Snapshot v1
+
+exports['toUpperCase 1'] = '"FOOBAR"'
+```
+
+The snapshot artifact should be committed alongside code changes, and reviewed as part of your code review process. On subsequent test runs, Vitest will compare the rendered output with the previous snapshot. If they match, the test will pass. If they don't match, either the test runner found a bug in your code that should be fixed, or the implementation has changed and the snapshot needs to be updated.
+
+## Inline Snapshots
+
+Similarly, you can use the [`toMatchInlineSnapshot()`](/api/#tomatchinlinesnapshot) to store the snapshot inline within the test file.
+
+```ts
+import { expect, it } from 'vitest'
+
+it('toUpperCase', () => {
+  const result = toUpperCase('foobar')
+  expect(result).toMatchInlineSnapshot()
+})
+```
+
+Instead of creating a snapshot file, Vitest will modify the test file directory to update the snapshot as a string:
+
+```ts
+import { expect, it } from 'vitest'
+
+it('toUpperCase', () => {
+  const result = toUpperCase('foobar')
+  expect(result).toMatchInlineSnapshot('"FOOBAR"')
+})
+```
+
+This allows you to see the expect output directly without jumpping across different files.
+
+## Updating Snapshots
+
+When the received value doesn't match with the snapshot, the test would fail and show you the difference between them. When the snapshot change is expected, you maybe want to update the snapshot from teh current state.
+
+In watch mode, you can press `u` key in the terminal to update the failed snapshot directly.
+
+Or you can use the `--updateSnapshot` or `-u` flag in the CLI to make Vitest into snapshot updating mode.
+
+```bash
+vitest -u
+```
+
+## Custom Serializer
+
+You can add your own logic to alter how your snapshots are serialized. Like Jest, Vitest has default serializers for built-in JavaScript types, HTML elements, ImmutableJS and for React elements.
+
+Example serializer module:
+
+```ts
+expect.addSnapshotSerializer({
+  serialize(val, config, indentation, depth, refs, printer) {
+    // `printer` is a function that serializes a value using existing plugins.
+    return `Pretty foo: ${printer(val.foo)}`
+  },
+  test(val) {
+    return val && Object.prototype.hasOwnProperty.call(val, 'foo')
+  },
+})
+```
+
+After adding a test like this:
+
+```ts
+test('foo snapshot test', () => {
+  const bar = {
+    foo: {
+      x: 1,
+      y: 2,
+    },
+  }
+
+  expect(bar).toMatchSnapshot()
+})
+```
+
+You will get the following snapshot:
+
+```
+Pretty foo: Object {
+  "x": 1,
+  "y": 2,
+}
+```
+
+We are using Jest's `pretty-format` for serializing snapshots. You can read more about it here: [pretty-format](https://github.com/facebook/jest/blob/main/packages/pretty-format/README.md#serialize).