Debian Codegraph @

workspaces/arborist/test/fixtures/README.md

raw
1 # `@npmcli/arborist` test fixtures
2
3 Hello, and welcome to Arborist's test fixture library!
4
5 Here you will find:
6
7 - A functional mock registry server, which can act as a caching proxy, so
8 that tests don't have to hit the main registry.
9 - A bunch of project layouts that exercise various cases, ranging from the
10 common and mundane, to the truly baffling and bizarre.
11 - Several of those project layouts snapshotted as `tap` fixture definition
12 objects, and a script to generate those fixture definitions.
13
14 ## Test Project Examples
15
16 Most of the folders in `test/fixtures/` are example project layouts.
17 Several of these are in fact published to the npm registry under the
18 `@isaacs/...` scope, but when used in tests, they should always be fetched
19 from the mock registry.
20
21 ### Symbolic Links
22
23 Several of these project folder examples involve symbolic links. The
24 symlinks are created the first time `test/fixtures/index.js` is loaded, and
25 are all ignored in the `.gitignore` file.
26
27 To create all the symlinks and add them to the `.gitignore` file
28 automatically:
29
30 ```
31 node test/fixtures/index.js
32 ```
33
34 To remove them all:
35
36 ```
37 node test/fixtures/index.js cleanup
38 ```
39
40 To add symlinks, put them on the list in `test/fixtures/index.js` rather
41 than creating them manually, as there are some platform-specific issues
42 that cause test failures on Windows otherwise.
43
44 ## Reify Test Case Fixtures
45
46 Since `Arborist.reify()` writes to the file system, it would not do to have
47 it dropping junk in those example project folders, as that would disturb
48 other tests running
49
50 The reify test case fixtures are stored in `test/fixtures/reify-cases/`.
51 To generate a new test case:
52
53 ```
54 node test/fixtures/create-reify-case.js <folder>
55 ```
56
57 where `<folder>` is a path to the test case example you wish to store.
58 Note that this encodes the entire folder in a single node module, and has
59 to be re-created fresh for each test run, so make sure it's not full of too
60 much garbage or extraneous files that aren't relevant to the test.
61
62 ## Mock Registry
63
64 The mock registry server is in `test/fixtures/server.js` and the contents are in
65 `test/fixtures/registry-mocks/content/`.
66
67 You can run the server directly by running:
68
69 ```
70 node test/fixtures/server.js
71 ```
72
73 In tests, it's loaded by requiring the server module, and then running the
74 exported method, passing in a `tap` test object, and using the exported
75 `registry` property as the registry config for all its business.
76
77 ```js
78 const {start, stop, registry} = require('../fixtures/server.js')
79 t.before(start)
80 t.teardown(stop)
81
82 t.test('something', async t => {
83 // set the registry config to the server we spun up
84 const arb = new Arborist({ ...options, registry })
85 })
86 ```
87
88 ### Updating Contents
89
90 When contents on the registry change, and you wish to update the mock
91 contents, the easiest way is to just delete the mock file you wish to
92 update, and then run the test with the mock registry server in proxy mode.
93
94 ```bash
95 # delete the some-package.json, some-package.min.json, and the
96 # tarball artifacts in some-package/*
97 rm -rf test/fixtures/registry-mocks/content/some-package*
98 npm run test-proxy test/arborist/reify.js
99 ```
100
101 The server will fetch whatever it doesn't have from the registry, and save
102 it in the appropriate place under `test/fixtures/registry-mocks/content/`.
103
104 There is also a script at
105 `test/fixtures/fetch-lock-contents.js` which will fetch and
106 store the packuments and tarballs referenced in a `package-lock.json` file.
107
108 And of course, you could just delete the entire `content` folder and run
109 `npm run test-proxy`, and it'll reload everything (and take a while).
110
111 Note that it's not a great idea to update the registry mocks too casually,
112 since changes in the packages published to the registry can cause tests to
113 no longer exercise the edge cases that they are intended to.
114
115 ### Audit Response and Audit Failure
116
117 To have the server respond to audit requests, use the exported
118 `auditResponse` method to set a file to use for the audit results.
119
120 If the file doesn't exist, and proxy mode is enabled, then it'll pass the
121 request up to the public registry, and save the result in the file
122 specified.
123
124 `auditFail()` and `auditResponse(file)` each return a function that will
125 un-hook the response from the server so you can use it for another test.
126
127 ```js
128 const registryServer = require('../fixtures/registry-mocks/server.js')
129 const {registry, auditResponse, auditFail} = registryServer
130 t.test('send an audit response', t => {
131 // makes it send an audit response file, or creates in proxy mode,
132 // if the file does not already exist.
133 t.teardown(auditResponse('.../path/to/audit.json'))
134
135 // makes it so that the audit fails with a 503
136 t.teardown(auditFail())
137
138 // then do some audits
139 })
140 ```