{"id":16603022,"url":"https://github.com/mchalapuk/fake-promise","last_synced_at":"2025-10-25T17:17:30.971Z","repository":{"id":49686244,"uuid":"103687906","full_name":"mchalapuk/fake-promise","owner":"mchalapuk","description":":pray: Total control over when ES6 promises are resolved. Intended for use in unit tests.","archived":false,"fork":false,"pushed_at":"2021-06-10T21:45:33.000Z","size":406,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-02T02:11:47.341Z","etag":null,"topics":["es6-promise","fake","javascript","mock","promise","resolve","testing","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mchalapuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-15T18:16:45.000Z","updated_at":"2022-02-17T18:16:50.000Z","dependencies_parsed_at":"2022-09-13T15:52:21.151Z","dependency_job_id":null,"html_url":"https://github.com/mchalapuk/fake-promise","commit_stats":null,"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchalapuk%2Ffake-promise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchalapuk%2Ffake-promise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchalapuk%2Ffake-promise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchalapuk%2Ffake-promise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mchalapuk","download_url":"https://codeload.github.com/mchalapuk/fake-promise/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238840756,"owners_count":19539608,"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","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":["es6-promise","fake","javascript","mock","promise","resolve","testing","unit-testing"],"created_at":"2024-10-12T00:46:37.180Z","updated_at":"2025-10-25T17:17:25.925Z","avatar_url":"https://github.com/mchalapuk.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FakePromise :pray:\n\n[\u003cimg src=\"https://badge.fury.io/js/fake-promise.svg\" alt=\"Current Version\"\u003e][npm-status]\n[\u003cimg src=\"https://travis-ci.org/mchalapuk/fake-promise.svg?branch=master\" alt=\"Build Status\" /\u003e][travis-status]\n[\u003cimg src=\"https://david-dm.org/mchalapuk/fake-promise/status.svg\" alt=\"Dependencies\"\u003e][david-status]\n[\u003cimg src=\"https://david-dm.org/mchalapuk/fake-promise/dev-status.svg\" alt=\"DevDependencies\" align=\"right\" /\u003e][david-status-dev]\n\n[npm-status]: https://npmjs.org/package/fake-promise\n[travis-status]: https://travis-ci.org/mchalapuk/fake-promise\n[david-status]: https://david-dm.org/mchalapuk/fake-promise\n[david-status-dev]: https://david-dm.org/mchalapuk/fake-promise?type=dev\n\n\u003e Total control over WHEN [ES6 promises][mdn-promise] are resolved or rejected.\n\n[mdn-promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise\n\n## Why would I want it?\n\n* FakePromise is a single-class library without any run-time dependencies,\n* It provides a **fully functional implementation of Promise with additional testing utilities**,\n* Fine grained control of resolution of each promise in a chain (`.then(...).then(...)`),\n* Thoroughly unit-tested and field-tested in several commercial projects,\n* Usable in modern JavaScript, TypeScript and CoffeeScript.\n\nThis package is intended for use in unit tests. For production, please use [Bluebird][bluebird].\n\n[bluebird]: https://github.com/petkaantonov/bluebird\n\n## Installation\n\n```shell\nnpm install --save-dev fake-promise\n```\n\n## Loading\n\n```javascript\n// node-style require\nconst { FakePromise } = require('fake-promise');\n\n// es6-style default import\nimport FakePromise from 'fake-promise';\n```\n\n## Documentation\n\nFor full documentation, please see JSDoc comments in [FakePromise][FakePromise] class.\n\n[FakePromise]: /src/FakePromise.ts\n\n```javascript\n/**\n * TL; DR\n */\nexport class FakePromise\u003cT\u003e implements Promise\u003cT\u003e {\n  // create already resolved/rejected instances of FakePromise (will resolve whole chain)\n  static resolve\u003cU = void\u003e(result ?: U | Promise\u003cU\u003e) : FakePromise\u003cU\u003e;\n  static reject\u003cU = void\u003e(error : any) : FakePromise\u003cU\u003e;\n\n  // no-arg constructor (without required executor as in standard promise)\n  constructor() {}\n\n  // promise specification methods (standard ES promise interface)\n  then\u003cU\u003e(onresolved : Callback\u003cU\u003e, onrejected ?: Callback\u003cany\u003e) : Promise\u003cU\u003e;\n  catch(onrejected : Callback\u003cany\u003e) : Promise\u003cany\u003e;\n  finally(onfulfilled : Callback\u003cvoid\u003e) : Promise\u003cvoid\u003e;\n\n  // resolve/reject full promise chain\n  resolve(result ?: T | Promise\u003cT\u003e) : void;\n  reject(error ?: any) : void;\n\n  // resolve/reject single promise in a chain and return next promise from the chain\n  resolveOne\u003cU = void\u003e(result ?: T | Promise\u003cT\u003e) : FakePromise\u003cU\u003e;\n  rejectOne\u003cU = void\u003e(error ?: any) : FakePromise\u003cU\u003e;\n\n  // set result/error of a promise without resolving/rejecting\n  // (to call resolve without arguments afterwards)\n  setResult(result : T | Promise\u003cT\u003e) : void;\n  setError(error : any) : void;\n}\n```\n## (Not So) Minimal Example\n\n```javascript\nimport FakePromise from 'fake-promise';\n\n/**\n * Async function to be tested.\n *\n * It calls `asyncFunctionDependency`, waits for it's promise\n * to be resolved, and returns the result of resolved promise.\n */\nasync function testedFunction(asyncFunctionDependency) {\n  try {\n    const result = await asyncFunctionDependency();\n    return result;\n  } catch (e) {\n    throw e;\n  }\n}\n\n/**\n * Tests of `testedFunction` using FakePromise.\n */\ndescribe('testedFunction(asyncDependency)', () =\u003e {\n  let dependencyPromise;\n  let asyncDependency;\n  let resultPromise;\n\n  beforeEach(() =\u003e {\n    // program `asyncDependency` to return a fresh instance of FakePromise\n    dependencyPromise = new FakePromise();\n    asyncDependency = sinon.stub().returns(dependencyPromise);\n\n    resultPromise = testedFunction(asyncDependency);\n\n    // At this point `dependencyPromise` is not yet resolved,\n    // so `resultPromise` isn't also.\n  });\n\n  describe('when after resolving dependency promise', () =\u003e {\n    const expectedResult = \"result\";\n\n    beforeEach(end =\u003e {\n      // could be also .resolveOne\n      dependencyPromise.resolve(expectedResult);\n\n      // At this point `dependencyPromise` is resolved, `resultPromise` is not.\n      // `setImmediate` is needed in order to wait single tick\n      // for resolution of implicit promise created by `await` keyword.\n      // `resultPromise` will be resolved before `end` is called.\n      setImmediate(end);\n    });\n\n    it('resolves result promise', () =\u003e {\n      // Returning promise so that the test will fail if promise is rejected.\n      return resultPromise.then(result =\u003e result.should.eql(expectedResult));\n    });\n  });\n\n  describe('when after rejecting dependency promise', () =\u003e {\n    const expectedError = new Error(\"fail\");\n\n    beforeEach(end =\u003e {\n      // could be also .rejectOne\n      dependencyPromise.reject(expectedError);\n\n      // At this point `dependencyPromise` is rejected, `resultPromise` is not.\n      // `setImmediate` is needed in order to wait single tick\n      // for rejection of implicit promise created by `await` keyword.\n      // `resultPromise` will be rejected before `end` is called.\n      setImmediate(end);\n    });\n\n    it('rejects result promise', () =\u003e {\n      // Testing rejection is tricky as both resolution and rejection cases\n      // must be tested in callbacks of the same promise instance\n      // (in single call to `.then(onResolved, onRejected)`).\n      return resultPromise.then(\n        result =\u003e { throw new Error(`expected rejection, got result: ${result}`) },\n        err =\u003e err.should.eql(expectedError),\n      );\n    });\n  });\n});\n```\n\n## Debugging Techniques\n\n### Printing Stack Traces\n\nFakePromise stores stack traces of all promise specifications, result\nprovisions and promise resolutions. When debugging problems with tests,\nit may be helpful to `console.log` one or more of stored traces.\n\n```javascript\n// print stack trace of call to `.then(...)` or `.catch`\nconsole.log(fakePromise.specifyTrace);\n\n// print stack trace of call to `.resove(...)`\nconsole.log(fakePromise.resolveTrace);\n\n// print stack trace of call to `.reject(...)`\nconsole.log(fakePromise.rejectTrace);\n\n// print stack trace of calls to `.setResult(...)`\nconsole.log(fakePromise.resultTrace);\n\n// print stack trace of calls to `.setResult(Promise)`\nconsole.log(fakePromise.promiseTrace);\n\n// print stack trace of calls to `.setError(...)`\nconsole.log(fakePromise.errorTrace);\n```\n\n### Using `.toString()`\n\nFakePromise implements `.toString()` method which provides information about\ninternal state of FakePromise instance. When encountering problems with\ndebugging async code, printing used instance of FakePromise may prove helpful.\n\n```javascript\nconsole.log(fakePromise);\n```\n\n## License\n\nCopyright \u0026copy; 2017 - 2019 Maciej Chałapuk. Released under [MIT license](LICENSE).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmchalapuk%2Ffake-promise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmchalapuk%2Ffake-promise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmchalapuk%2Ffake-promise/lists"}