{"id":13240,"library":"givens","title":"Easy Test Setup without Side Effects","description":"Givens is a testing utility designed to facilitate clean, maintainable, and side-effect-free test setups, primarily for JavaScript and TypeScript projects using Jest, Mocha, or Jasmine. Its behavior is inspired by RSpec's 'given' keyword, offering a familiar pattern for developers with Ruby backgrounds. The library helps prevent common testing pitfalls such as cross-contamination between tests, order-dependent tests, and unpredictable behavior when running subsets of tests (e.g., with `.only` or `.skip`). It achieves this by managing a cached, scoped value for 'given' variables, ensuring values are fresh for each test and correctly reverted across `describe` blocks. The current stable version is 1.3.9, with a recent cadence of security and dependency updates, indicating active maintenance rather than feature-heavy releases.","status":"active","version":"1.3.9","language":"javascript","source_language":"en","source_url":"https://github.com/enova/givens","tags":["javascript","jest","mocha","given","let","test","testing","unit","rspec","typescript"],"install":[{"cmd":"npm install givens","lang":"bash","label":"npm"},{"cmd":"yarn add givens","lang":"bash","label":"yarn"},{"cmd":"pnpm add givens","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For local, per-file usage in CommonJS, use `const getGiven = require('givens').default;` if targeting older Node environments, but ESM is preferred.","wrong":"const getGiven = require('givens');","symbol":"getGiven","correct":"import getGiven from 'givens';"},{"note":"This import is typically placed in a testing framework's setup file (e.g., `setupFilesAfterEnv` in Jest) to make `given` globally available without explicit per-file imports.","symbol":"given (global)","correct":"import 'givens/setup';"},{"note":"When using TypeScript, define an interface for your 'given' keys and their types to ensure type safety with the returned `given` object.","symbol":"getGiven<MyVars>","correct":"import getGiven from 'givens'; interface MyVars { /* ... */ } const given = getGiven<MyVars>();"}],"quickstart":{"code":"import getGiven from 'givens';\n\ninterface CalculatorVars {\n  a: number;\n  b: number;\n  sum: number;\n}\n\ndescribe('Calculator', () => {\n  const given = getGiven<CalculatorVars>();\n\n  given('a', () => 1);\n  given('b', () => 2);\n  given('sum', () => given.a + given.b);\n\n  it('adds two numbers', () => {\n    expect(given.sum).toBe(3);\n  });\n\n  describe('when numbers are different', () => {\n    given('b', () => 5); // overrides 'b' for this describe block\n\n    it('adds correctly with overridden b', () => {\n      expect(given.sum).toBe(6); // 1 + 5\n    });\n\n    describe('when overriding a again', () => {\n        given('a', () => 10);\n\n        it('adds correctly with a and b overridden', () => {\n            expect(given.sum).toBe(15); // 10 + 5\n        });\n    });\n  });\n\n  // After the 'when numbers are different' block, 'b' reverts to its outer scope value (2)\n  it('reverts to original b value', () => {\n    expect(given.sum).toBe(3); // 1 + 2\n  });\n});","lang":"typescript","description":"This quickstart demonstrates how to define and override 'given' variables with type safety in TypeScript, showing how `givens` manages scope and caching."},"warnings":[{"fix":"Ensure Jest configuration uses `setupFilesAfterEnv: ['givens/setup.js']`.","message":"When using the global `givens/setup` import with Jest, it MUST be configured under `setupFilesAfterEnv` in your Jest config, not `setupFiles`. Using `setupFiles` will cause the global `given` function to be unavailable within your test files.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to v1.3.0 or later and adopt the recommended `getGiven<MyVars>()` pattern for improved type safety.","message":"Prior to v1.3.0, TypeScript support was less robust and required more manual type declarations. Version 1.3.0 and newer significantly improved TypeScript compatibility, potentially breaking older, custom type workarounds.","severity":"breaking","affected_versions":"<1.3.0"},{"fix":"Use `givens` exclusively within Node.js testing environments (e.g., Jest, Mocha, Jasmine running in Node).","message":"The library explicitly states that 'Non Node environments are untested, and may not work.' While it's JavaScript, browser environments or other runtimes are not officially supported.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly update `givens` to its latest version (e.g., using `npm update givens` or `yarn upgrade givens`) and monitor for new releases.","message":"Frequent 'Security Updates' releases (e.g., 1.3.5, 1.3.6, 1.3.7, 1.3.8, 1.3.9) indicate a proactive approach to patching dependencies, but also highlight the importance of keeping `givens` updated to the latest minor version to ensure supply chain security.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For local usage: `import getGiven from 'givens'; const given = getGiven();`. For global usage: configure your test runner with `setupFilesAfterEnv: ['givens/setup.js']` (for Jest) or equivalent.","cause":"The `given` function was not imported locally or set up globally via `givens/setup`.","error":"ReferenceError: given is not defined"},{"fix":"Ensure you call `const given = getGiven();` after importing `getGiven`, or verify your test runner's global setup is correctly configured and applied.","cause":"Attempting to use `given` without calling `getGiven()` first when using local imports, or if the global setup failed.","error":"TypeError: given is not a function"},{"fix":"Update your TypeScript interface (e.g., `interface SomeVars { myKey: SomeType; }`) to include all keys you intend to use with `given`.","cause":"When using TypeScript, the key `myKey` was not included in the interface provided to `getGiven<SomeVars>()`, or there is a typo.","error":"Property 'myKey' does not exist on type 'Given<SomeVars>'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}