givens

library1.3.9jsnpmunverified

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.

testing

npm install givens

github ↗package ↗

INSTALL

IMPORT

SIG · GIVENS

givens

testingjavascriptv1.3.9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getGiven

✓ import getGiven from 'givens';

✗ const getGiven = require('givens');

For local, per-file usage in CommonJS, use `const getGiven = require('givens').default;` if targeting older Node environments, but ESM is preferred.

given (global)

✓ import 'givens/setup';

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.

getGiven<MyVars>

✓ import getGiven from 'givens'; interface MyVars { /* ... */ } const given = getGiven<MyVars>();

When using TypeScript, define an interface for your 'given' keys and their types to ensure type safety with the returned `given` object.

This quickstart demonstrates how to define and override 'given' variables with type safety in TypeScript, showing how `givens` manages scope and caching.

import getGiven from 'givens'; interface CalculatorVars { a: number; b: number; sum: number; } describe('Calculator', () => { const given = getGiven<CalculatorVars>(); given('a', () => 1); given('b', () => 2); given('sum', () => given.a + given.b); it('adds two numbers', () => { expect(given.sum).toBe(3); }); describe('when numbers are different', () => { given('b', () => 5); // overrides 'b' for this describe block it('adds correctly with overridden b', () => { expect(given.sum).toBe(6); // 1 + 5 }); describe('when overriding a again', () => { given('a', () => 10); it('adds correctly with a and b overridden', () => { expect(given.sum).toBe(15); // 10 + 5 }); }); }); // After the 'when numbers are different' block, 'b' reverts to its outer scope value (2) it('reverts to original b value', () => { expect(given.sum).toBe(3); // 1 + 2 }); });

Debug

Known issues

gotchaWhen 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.

fix

Ensure Jest configuration uses `setupFilesAfterEnv: ['givens/setup.js']`.

affects: >=1.0.0

breakingPrior 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.

fix

Upgrade to v1.3.0 or later and adopt the recommended `getGiven<MyVars>()` pattern for improved type safety.

affects: <1.3.0

gotchaThe 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.

fix

Use `givens` exclusively within Node.js testing environments (e.g., Jest, Mocha, Jasmine running in Node).

affects: >=1.0.0

gotchaFrequent '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.

fix

Regularly update `givens` to its latest version (e.g., using `npm update givens` or `yarn upgrade givens`) and monitor for new releases.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: given is not defined

The `given` function was not imported locally or set up globally via `givens/setup`.

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.

TypeError: given is not a function

Attempting to use `given` without calling `getGiven()` first when using local imports, or if the global setup failed.

fix

Ensure you call `const given = getGiven();` after importing `getGiven`, or verify your test runner's global setup is correctly configured and applied.

Property 'myKey' does not exist on type 'Given<SomeVars>'

When using TypeScript, the key `myKey` was not included in the interface provided to `getGiven<SomeVars>()`, or there is a typo.

fix

Update your TypeScript interface (e.g., `interface SomeVars { myKey: SomeType; }`) to include all keys you intend to use with `given`.

Upgrade

Version history

1.3.9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/enova/givens ↗

packagehttps://www.npmjs.com/package/givens ↗