path-serializer 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +139 -11
  2. package/dist/cjs/index.cjs +643 -0
  3. package/dist/esm/index.js +616 -0
  4. package/package.json +18 -15
  5. package/dist/cjs/index.js +0 -930
  6. package/dist/esm/index.mjs +0 -899
package/README.md CHANGED
@@ -2,27 +2,47 @@
2
2
 
3
3
  [![npm latest version](https://img.shields.io/npm/v/path-serializer?style=flat-square&color=98c379)](https://www.npmjs.com/package/path-serializer)
4
4
 
5
- 1. stabilize pnpm dependencies path in snapshot
6
- 2. transform win32 path to posix path
7
- 3. escapeEOL \r\n -> \n
8
- and more...
5
+ A snapshot serializer that normalizes system-specific paths into stable, readable placeholders — designed for Vitest, Jest, and Rstest.
6
+
7
+ - Stabilize pnpm dependencies path in snapshot (including `enableGlobalVirtualStore`)
8
+ - Transform win32 path to posix path
9
+ - Replace absolute paths with placeholders (`<ROOT>`, `<WORKSPACE>`, `<HOME>`, `<TEMP>`)
10
+ - Handle `file://` protocol URLs
11
+ - Escape EOL (`\r\n` -> `\n`)
12
+ - Normalize ANSI color codes
9
13
 
10
14
  ```ts
11
15
  // __snapshots__/index.test.ts.snap
12
- // 😭 bad
16
+
17
+ // 😭 Without path-serializer — fragile, platform-specific, unreadable
13
18
  {
14
19
  "loader" : "D:\\user\\rspack\\node_modules\\.pnpm\\css-loader@6.11.0_@rspack+core@packages+rspack_webpack@5.94.0_@swc+core@1.4.0_@swc+helpers@0._jlcdgjlw2ezzhg43ml3d627wdu\\node_modules\\css-loader\\utils.ts"
15
20
  }
16
- //😎👍🏻 good
21
+
22
+ // 😎 With path-serializer — stable, cross-platform, clean
17
23
  {
18
- "loader" : "<ROOT>/node_modules/<PNPM_INNER>/css-loader/utils.ts"
24
+ "loader" : "<PNPM_INNER>/css-loader/utils.ts"
19
25
  }
20
26
  ```
21
27
 
28
+ ## Installation
29
+
30
+ ```bash
31
+ # npm
32
+ npm install path-serializer -D
33
+
34
+ # pnpm
35
+ pnpm add path-serializer -D
36
+ ```
37
+
22
38
  ## Usage
23
39
 
40
+ ### Basic
41
+
24
42
  ```typescript
25
43
  // vitest.setup.ts
44
+ import path from 'node:path';
45
+ import { expect } from 'vitest';
26
46
  import { createSnapshotSerializer } from 'path-serializer';
27
47
 
28
48
  expect.addSnapshotSerializer(
@@ -32,12 +52,120 @@ expect.addSnapshotSerializer(
32
52
  );
33
53
  ```
34
54
 
35
- More features can be found in [./src/types.ts](https://github.com/rspack-contrib/path-serializer/blob/main/src/types.ts)
55
+ ### With Workspace (Monorepo)
56
+
57
+ ```typescript
58
+ expect.addSnapshotSerializer(
59
+ createSnapshotSerializer({
60
+ root: path.join(__dirname, '../..'),
61
+ workspace: path.join(__dirname, '..'),
62
+ }),
63
+ );
64
+ ```
65
+
66
+ This replaces:
67
+
68
+ - Workspace paths → `<WORKSPACE>/...`
69
+ - Root paths → `<ROOT>/...`
70
+
71
+ ### Custom Replacements
72
+
73
+ Use `replace` and `replacePost` to add custom path matchers:
74
+
75
+ ```typescript
76
+ expect.addSnapshotSerializer(
77
+ createSnapshotSerializer({
78
+ root: path.join(__dirname, '..'),
79
+ replace: [
80
+ { match: /port\s\d+/, mark: 'PORT' },
81
+ { match: '/specific/path', mark: 'CUSTOM' },
82
+ ],
83
+ }),
84
+ );
85
+ ```
86
+
87
+ ### Hooks
88
+
89
+ Use `beforeSerialize` and `afterSerialize` for custom pre/post processing:
90
+
91
+ ```typescript
92
+ expect.addSnapshotSerializer(
93
+ createSnapshotSerializer({
94
+ root: path.join(__dirname, '..'),
95
+ beforeSerialize: (val) => val.replace(/hash:\w{8}/g, 'hash:<HASH>'),
96
+ afterSerialize: (val) => val.trim(),
97
+ }),
98
+ );
99
+ ```
100
+
101
+ ## Options
102
+
103
+ ### `root`
104
+
105
+ - **Type:** `string`
106
+ - **Default:** `process.cwd()`
107
+
108
+ Repository root path. Paths under this directory are replaced with `<ROOT>`.
109
+
110
+ ### `workspace`
111
+
112
+ - **Type:** `string`
113
+ - **Default:** `''`
114
+
115
+ Workspace root path (for monorepos). Paths under this directory are replaced with `<WORKSPACE>`.
116
+
117
+ ### `replace`
118
+
119
+ - **Type:** `PathMatcher[]`
120
+
121
+ Custom matchers applied **before** built-in replacements.
122
+
123
+ ### `replacePost`
124
+
125
+ - **Type:** `PathMatcher[]`
126
+
127
+ Custom matchers applied **after** built-in replacements.
128
+
129
+ ### `beforeSerialize`
130
+
131
+ - **Type:** `(val: string) => string`
132
+
133
+ Transform the raw string before any replacements.
134
+
135
+ ### `afterSerialize`
136
+
137
+ - **Type:** `(val: string) => string`
138
+
139
+ Transform the final string after all replacements.
140
+
141
+ ### `features`
142
+
143
+ Toggle individual features (all enabled by default):
144
+
145
+ | Feature | Default | Description |
146
+ |---|---|---|
147
+ | `replaceWorkspace` | `true` | `/foo/packages/core/src` → `<WORKSPACE>/src` |
148
+ | `replaceRoot` | `true` | `/foo/node_modules/.pnpm` → `<ROOT>/node_modules/.pnpm` |
149
+ | `replaceWorkspaceWithFileProtocol` | `true` | `file:///foo/packages/core/src` → `<WORKSPACE>/src` |
150
+ | `replaceRootWithFileProtocol` | `true` | `file:///foo/node_modules/.pnpm` → `<ROOT>/node_modules/.pnpm` |
151
+ | `replacePnpmInner` | `true` | Collapse pnpm's long `.pnpm/...` and global virtual store `pnpm/store/.../links/...` paths to `<PNPM_INNER>` |
152
+ | `replaceTmpDir` | `true` | `os.tmpdir()` paths → `<TEMP>` |
153
+ | `replaceHomeDir` | `true` | `os.homedir()` paths → `<HOME>` |
154
+ | `transformWin32Path` | `true` | Convert `D:\\foo\\bar` to `/d/foo/bar` |
155
+ | `transformCLR` | `true` | Normalize ANSI color escape codes |
156
+ | `escapeDoubleQuotes` | `true` | Escape `"` to `\"` |
157
+ | `escapeEOL` | `true` | Normalize `\r\n` to `\n` |
158
+ | `addDoubleQuotes` | `true` | Wrap output in double quotes |
159
+
160
+ More details can be found in [./src/types.ts](https://github.com/rspack-contrib/path-serializer/blob/main/src/types.ts).
36
161
 
37
162
  ## Showcases
38
163
 
39
- [Rslib](https://github.com/web-infra-dev/rslib/blob/3ff6859eb38171c731e447a1364afc021f8c501a/tests/setupVitestTests.ts)
164
+ - [Rslib](https://github.com/web-infra-dev/rslib/blob/3ff6859eb38171c731e447a1364afc021f8c501a/tests/setupVitestTests.ts)
165
+ - [Rsbuild](https://github.com/web-infra-dev/rsbuild/blob/a50eafa3519caaa66ecd6b0ccb2897a8194781ff/scripts/test-helper/vitest.setup.ts)
166
+ - [Rspack](https://github.com/web-infra-dev/rspack/blob/5a6162c/packages/rspack-test-tools/src/helper/expect/placeholder.ts)
167
+ - [Rspress](https://github.com/web-infra-dev/rspress/blob/8d620050cc2590954838e201d39c10744b6d1bac/scripts/test-helper/rstest.setup.ts)
40
168
 
41
- [Rsbuild](https://github.com/web-infra-dev/rsbuild/blob/a50eafa3519caaa66ecd6b0ccb2897a8194781ff/scripts/test-helper/vitest.setup.ts)
169
+ ## License
42
170
 
43
- [Rspack](https://github.com/web-infra-dev/rspack/blob/5a6162c/packages/rspack-test-tools/src/helper/expect/placeholder.ts)
171
+ [MIT](./LICENSE)