{"id":14263258,"url":"https://github.com/streamich/spyfs","last_synced_at":"2025-08-12T08:06:51.944Z","repository":{"id":24027899,"uuid":"100426564","full_name":"streamich/spyfs","owner":"streamich","description":"Node filesystem spies and mocks","archived":false,"fork":false,"pushed_at":"2025-07-27T15:24:08.000Z","size":97,"stargazers_count":48,"open_issues_count":11,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-27T17:36:35.822Z","etag":null,"topics":["filesystem","fs","spy","test","testing"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/spyfs","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/streamich.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-08-15T23:10:36.000Z","updated_at":"2025-07-27T15:24:10.000Z","dependencies_parsed_at":"2024-02-21T08:29:51.764Z","dependency_job_id":"914ff297-a1d9-4b63-9f79-5dce89de6175","html_url":"https://github.com/streamich/spyfs","commit_stats":{"total_commits":236,"total_committers":4,"mean_commits":59.0,"dds":0.4152542372881356,"last_synced_commit":"99ac8e6058d5c7036d0554293a4bb6aee5dc8995"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/streamich/spyfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamich%2Fspyfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamich%2Fspyfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamich%2Fspyfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamich%2Fspyfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/streamich","download_url":"https://codeload.github.com/streamich/spyfs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamich%2Fspyfs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270024697,"owners_count":24514054,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filesystem","fs","spy","test","testing"],"created_at":"2024-08-22T13:05:54.155Z","updated_at":"2025-08-12T08:06:51.904Z","avatar_url":"https://github.com/streamich.png","language":"JavaScript","readme":"# spyfs [![npm-img]][npm-url]\n\nSpy on filesystem calls. Create file system mocks. Use for testing.\n\nInstall:\n\n    npm install --save spyfs\n\nCreate a new file system that spies:\n\n```js\nimport * as fs from 'fs';\nimport {spy} from 'spyfs';\n\nconst sfs = spy(fs);\n```\n\nNow you can use `sfs` for all your filesystem operations.\n\n```js\nconst data = sfs.readFileSync('./package.json').toString();\n```\n\nSubscribe to all actions happening on that filesystem:\n\n```js\nsfs.subscribe(action =\u003e {\n    // ...\n});\n```\n\nEvery time somebody uses `sfs`, the subscription callback will be called.\nYou will receive a single argument: an `action` which is a `Promise` object\ncontaining all the information about the performed filesystem operation and its result.\n\nYou can also subscribe by providing a listener at creation:\n\n```js\nconst sfs = spy(fs, action =\u003e {\n    // ...\n});\n```\n\n\n### Want to spy on real filesystem?\n\nOverwrite the real `fs` module using [`fs-monkey`][fs-monkey] to spy on all filesystem\ncalls:\n\n```js\nimport {patchFs} from 'fs-monkey';\n\npatchFs(sfs);\n```\n\n\n### Use `async/await`\n\n`spyfs` returns *actions* which are instances of the `Promise` constructor,\nso you can use *asynchronous* functions for convenience:\n\n```js\nconst sfs = spy(fs, async function(action) {\n    console.log(await action); // prints directory files...\n});\n\nsfs.readdir('/', () =\u003e {});\n```\n\n\n### Use with [`memfs`][memfs]\n\nYou can use `spyfs` with any *fs-like* object, including [`memfs`][memfs]:\n\n```js\nimport {fs} from 'memfs';\nimport {spy} from 'spyfs';\n\nconst sfs = spy(fs, async function(action) {\n    console.log(await action); // bar\n});\n\nsfs.writeFile('/foo', 'bar', () =\u003e {});\nsfs.readFile('/foo', 'utf8', () =\u003e {});\n```\n\n\n### Action properties\n\n`spyfs` actions have extra properties that tell you more about the action\nbeing executed:\n\n  - `action.method` *(string)* - name of filesystem method called.\n  - `action.isAsync` *(boolean)* - whether the filesystem method called was asynchronous.\n  - `action.args` *(Array)* - list of arguments with which the method was called (sans callback).\n\n```js\nconst sfs = spy(fs, action =\u003e {\n    console.log(action.method); // readdir, readdirSync\n    console.log(action.isAsync); // true, false\n    console.log(action.args); // [ '/' ], [ '/' ]\n});\n\nsfs.readdir('/', () =\u003e {});\nsfs.readdirSync('/');\n```\n\n\n### Subscribe to events\n\nThe returned filesystem object is also an event emitter, you can subscribe\nto specific filesystem actions using the `.on()` method, in that case you\nwill receive only actions for that method:\n\n```js\nsfs.on('readdirSync', async function(action) {\n    console.log(action.args, await action);\n});\n\nsfs.readdirSync('/');\n```\n\nListening for `action` event is equivalent to subscribing using `.subscribe()`.\n\n```js\nsfs.on('action', listener);\nsfs.subscribe(listener);\n```\n\n\n## Mock responses\n\nYou can overwrite what is returned by the filesystem call at runtime or even\nthrow your custom errors, this way you can mock any filesystem call:\n\nFor example, prohibit `readFileSync` for `/usr/foo/.bashrc` file:\n\n```js\nsfs.on('readFileSync', ({args, reject}) =\u003e {\n    if(args[0] === '/usr/foo/.bashrc')\n        reject(new Error(\"Cant't touch this!\"));\n});\n```\n\n\n### Sync mocking\n\n#### `action.resolve(result)`\n\nReturns to the user `result` as successfully executed action, below\nall operations `readFileSync` will return `'123'`:\n\n```js\nsfs.on('readFileSync', action =\u003e {\n    action.resolve('123');\n});\n```\n\n#### `action.reject(error)`\n\nThrows `error`:\n\n```js\nsfs.on('statSync', action =\u003e {\n    action.reject(new Error('This filesystem does not support stat'));\n});\n```\n\n#### `action.exec()`\n\nExecutes an action user was intended to perform and returns back result\nonly to you. This method can throw.\n\n```js\nsfs.on('readFileSync', action =\u003e {\n    const result = action.exec();\n    if(result.length \u003e 100) action.reject(new Error('File too long'));\n});\n```\n\n#### `action.result`\n\n`result` is a reference to the `action` for your convenience:\n\n### Async mocking\n\nJust like sync mocking actions support `resolve`, `reject` and `exec` methods,\nbut, in addition, async mocking also has `pause` and `unpause` methods.\n\n#### `action.resolve(results)`\n\nSuccessfully executes user's filesystem call. `results` is an array, because\nsome Node's async filesystem calls return more than one result.\n\n```js\nsfs.on('readFile', ({resolve}) =\u003e {\n    resolve(['123']);\n});\n```\n\n#### `action.reject(error)`\n\nFails filesystem call and returns your specified error.\n\n```js\nsfs.on('readFile', ({reject}) =\u003e {\n    reject(new Error('You cannot touch this file!'));\n});\n```\n\n#### `action.pause()`\n\nPauses the async filesystem call until you un-pause it.\n\n```js\nsfs.on('readFile', ({pause}) =\u003e {\n    pause();\n    // The readFile operation will never end,\n    // if you don't unpause it.\n});\n```\n\nPausing is useful if you want to perform some other async IO before yielding\nback to the original filesystem operation.\n\n#### `action.unpause()`\n\nUn-pauses previously pauses filesystem operation:\n\n```js\nsfs.on('readFile', ({pause, unpause}) =\u003e {\n    // This effectively does nothing:\n    pause();\n    unpause();\n});\n```\n\n#### `action.exec()`\n\nExecutes user's intended filesystem call and returns the result only to you.\nUnlike the sync version `exec`, async `exec` returns a promise.\n\nYou should use it together with `pause()` and `unpause()`.\n\n```js\nsfs.on('readFile', ({exec, pause, unpause, reject}) =\u003e {\n    pause();\n    exec().then(result =\u003e {\n        if(result.length \u003c 100) {\n            reject(new Error('File too small'));\n        } else {\n            unpause();\n        }\n    });\n});\n```\n\nUse `async/await` with `exec()`:\n\n```js\nsfs.on('readFile', async function({exec, pause, unpause, reject}) {\n    pause();\n    let result = await exec();\n    if(result.length \u003c 100) {\n        reject(new Error('File too small'));\n    } else {\n        unpause();\n    }\n});\n```\n\n#### `action.result`\n\n`result` is a reference to the `action` for your convenience:\n\n\n## `Spy` constructor\n\nCreate spying filesystems manually:\n\n```js\nimport {Spy} from 'spyfs';\n```\n\n#### `new Spy(fs[, listener])`\n\n`fs` is the file system to spy on. Note that `Spy` will not overwrite or\nin any way modify your original filesystem, but rather it will create a\nnew object for you.\n\n`listener` is an optional callback that will be set using the `.subscribe()`\nmethod, see below.\n\n#### `sfs.subscribe(listener)`\n\nSubscribe to all filesystem actions:\n\n```js\nconst sfs = new Spy(fs);\nsfs.subscribe(action =\u003e {\n\n});\n```\n\nIt is equivalent to calling `sfs.on('action', listener)`.\n\n#### `sfs.unsubscribe(listener)`\n\nUnsubscribes your listener. It is equivalent to calling `sfs.off('action', listener)`.\n\n#### `sfs.on(method, listener)`\n\nSubscribes to a specific filesystem call.\n\n```js\nsfs.on('readFile', listener);\n```\n\n#### `sfs.off(method, listener)`\n\nUnsubscribes from a specific filesystem call.\n\n\n\n[npm-url]: https://www.npmjs.com/package/spyfs\n[npm-img]: https://img.shields.io/npm/v/spyfs.svg\n[memfs]: https://github.com/streamich/memfs\n[unionfs]: https://github.com/streamich/unionfs\n[linkfs]: https://github.com/streamich/linkfs\n[spyfs]: https://github.com/streamich/spyfs\n[fs-monkey]: https://github.com/streamich/fs-monkey\n\n\n\n\n\n# License\n\nThis is free and unencumbered software released into the public domain.\n\nAnyone is free to copy, modify, publish, use, compile, sell, or\ndistribute this software, either in source code form or as a compiled\nbinary, for any purpose, commercial or non-commercial, and by any\nmeans.\n\nIn jurisdictions that recognize copyright laws, the author or authors\nof this software dedicate any and all copyright interest in the\nsoftware to the public domain. We make this dedication for the benefit\nof the public at large and to the detriment of our heirs and\nsuccessors. We intend this dedication to be an overt act of\nrelinquishment in perpetuity of all present and future rights to this\nsoftware under copyright law.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR\nOTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,\nARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR\nOTHER DEALINGS IN THE SOFTWARE.\n\nFor more information, please refer to \u003chttp://unlicense.org/\u003e\n","funding_links":[],"categories":["testing"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreamich%2Fspyfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstreamich%2Fspyfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreamich%2Fspyfs/lists"}