{"id":13683457,"url":"https://github.com/enova/givens","last_synced_at":"2025-03-24T17:31:23.350Z","repository":{"id":37881132,"uuid":"234115732","full_name":"enova/givens","owner":"enova","description":"Easy test setup without side effects.","archived":false,"fork":false,"pushed_at":"2023-01-07T13:46:11.000Z","size":1221,"stargazers_count":25,"open_issues_count":27,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-19T04:02:35.229Z","etag":null,"topics":["javascript","javascript-tests","jest","jest-tests","mocha","rspec","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/enova.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":"2020-01-15T15:51:45.000Z","updated_at":"2025-03-01T00:50:54.000Z","dependencies_parsed_at":"2023-02-07T08:11:21.085Z","dependency_job_id":null,"html_url":"https://github.com/enova/givens","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enova%2Fgivens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enova%2Fgivens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enova%2Fgivens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enova%2Fgivens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/enova","download_url":"https://codeload.github.com/enova/givens/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245318928,"owners_count":20595866,"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":["javascript","javascript-tests","jest","jest-tests","mocha","rspec","typescript"],"created_at":"2024-08-02T13:02:11.994Z","updated_at":"2025-03-24T17:31:22.884Z","avatar_url":"https://github.com/enova.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"/documentation/logo-light.png\" alt=\"givens\" width=\"300\"\u003e\n  \u003cbr /\u003e\n  \u003cbr /\u003e\n  \u003ca href='https://www.npmjs.com/package/givens'\u003e\u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/v/givens\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/workflow/status/enova/givens/CD?label=build\"\u003e\n  \u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/workflow/status/enova/givens/CI?label=tests\"\u003e\n  \u003ca href=\"https://codecov.io/gh/enova/givens\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/enova/givens/branch/master/graph/badge.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href='https://github.com/enova/givens/blob/master/LICENSE'\u003e\u003cimg alt=\"MIT License\" src=\"https://img.shields.io/github/license/enova/givens\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nEasy test setup without side effects.\n\nFor use with [jest](https://github.com/facebook/jest), [mocha](https://github.com/mochajs/mocha), and [jasmine](https://github.com/jasmine/jasmine.github.io).\nBehavior based on [rspec](https://github.com/enova/givens/blob/master), syntax inspired by [given2](https://github.com/tatyshev/given2)\n\n---\n\n## Why?\n\nIf you or your team have ruby and rspec experience, and are moving to a javascript based library, this will make the experience of writing javascript tests very similar to that of writing rspec tests.\n\nEven if you don't come from a ruby background, givens can help you write maintainable tests quickly, while avoiding many of the side effects traditional JavaScript testing often has, such as:\n\n- testing different methods on the same object in multiple tests can result in cross-contamination.\n- tests can depend on order; and break when reordered.\n- Running only some tests in a single file (like via jest’s `.skip` or `.only`) can make tests behave unpredictably.\n\nGivens, when used correctly solves all of these, dries up your tests, and might even make them more readable, while still letting you use `beforeEach` and `afterEach`.\n\n---\n\n## What does it do?\n\nwhen you call `getGiven()`, givens calls `afterEach` with a callback that clears the cache. Because this `afterEach` hook is declared first, it will run after every other `afterEach` in every scope.\n\nwhen you call `given(key, callback)`, givens calls the following lifecycle functions:\n\n- `beforeAll`, with a hook which pushes `callback` onto a stack of functions for `key` and makes sure there is an accessor present for key, which simply calls the topmost function on the stack and returns the result.\n- `afterAll`, with a hook which pops `callback` back off the stack of functions for `key`, and deletes the accessor if the stack is now empty.\n\n## Getting Started\n\n### Prerequisites\n\nThis package should work fine for any javascript or typescript project that uses jest or mocha tests. Non Node environments are untested, and may not work.\n\n### Installing\nfirst, install from npm:\n```bash\nnpm install --save-dev givens\n```\nor\n```bash\nyarn add --dev givens\n```\n#### global installation\n```javascript\nimport 'givens/setup';\n```\nor add to testing framework config, for example in jest:\n```javascript\n{\n  setupFilesAfterEnv: [ // this CANNOT be setupFiles\n    'givens/setup.js',\n  ],\n}\n```\nthen you can use the `given` keyword without importing.\n#### local installation\nin the test file, use the following import:\n```javascript\nimport getGiven from 'givens';\nconst given = getGiven();\n```\nor in typescript\n```typescript\nimport getGiven from 'givens';\ninterface myVars {\n  var1: number; // the keys you intend to use\n  var2: string; // and their types\n}\nconst given = getGiven\u003cmyVars\u003e();\n```\n\n---\n## Usage\n\nWhen you call `given(myKey, callback)`, givens stores the callback function you give it. When you go to retrieve the key (via `given.myKey`) givens will execute the most recent callback you have given for the key, and cache the value. Additionally, if you call `given()` inside a describe, the callback will revert to the previous one given for `myKey` after executing all tests in the describe, allowing you to override a given value for a set of tests. The cache is cleared after every test.\n\n```javascript\ndescribe('basic overriding behavior', () =\u003e {\n  given('var1', () =\u003e 'initial value');\n  given('var2', () =\u003e {\n    return 'the value is: ' + given.var1;\n  });\n\n  it('has initial value', () =\u003e {\n    expect(given.var2).toEqual('the value is: initial value');\n  });\n\n  describe('with new value', () =\u003e {\n    given('var1', () =\u003e 'overridden value');\n\n    it('has overridden value', () =\u003e {\n      expect(given.var2).toEqual('the value is: overridden value');\n    });\n  });\n\n  it('has initial value again', () =\u003e {\n    expect(given.var2).toEqual('the value is: initial value');\n  });\n});\n```\n\nFor more examples of usage for your particular setup, read through the integration tests. They are examples of how to use the library as intended (and in some cases how it's not supposed to be used).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenova%2Fgivens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenova%2Fgivens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenova%2Fgivens/lists"}