{"id":11207,"library":"kefir-test-utils","title":"Kefir Testing Utilities","description":"Kefir-test-utils is a dedicated, framework-agnostic library providing a set of utilities specifically designed for testing Kefir.js observables. It enables developers to write robust unit tests for reactive streams by offering tools to control time, watch observable emissions, and assert their behavior over virtual timelines. The current stable version is 2.0.0, released in late 2023, following a period of maintenance and dependency upgrades. While its release cadence appears measured, recent updates indicate active development, focusing on modern JavaScript environments and dependency health. Key differentiators include its tight integration and specialization for the Kefir.js ecosystem, having been extracted from `chai-kefir` to offer a standalone, reusable set of testing primitives without tying to a specific assertion library or test framework. It is crucial for anyone building complex reactive applications with Kefir.js who needs precise control over testing asynchronous stream logic, offering a structured approach to virtual time testing that is typically more challenging with general-purpose testing tools.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/kefirjs/kefir-test-utils","tags":["javascript","kefir","testing","unit testing","typescript"],"install":[{"cmd":"npm install kefir-test-utils","lang":"bash","label":"npm"},{"cmd":"yarn add kefir-test-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add kefir-test-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for creating and testing observables.","package":"kefir","optional":false}],"imports":[{"note":"Primary utility for running tests with virtual time. ESM imports are preferred since v2.0.0 dropped Node.js v10 support, moving towards modern JavaScript practices.","wrong":"const withTime = require('kefir-test-utils').withTime","symbol":"withTime","correct":"import { withTime } from 'kefir-test-utils'"},{"note":"Used to observe and collect emissions from Kefir observables within a test context for assertion.","wrong":"const watch = require('kefir-test-utils').watch","symbol":"watch","correct":"import { watch } from 'kefir-test-utils'"},{"note":"A convenience function combining `withTime` and `watch` for common scenarios. It is a named export, despite its singular name suggesting a potential default export.","wrong":"import watchWithTime from 'kefir-test-utils'","symbol":"watchWithTime","correct":"import { watchWithTime } from 'kefir-test-utils'"}],"quickstart":{"code":"import * as Kefir from 'kefir';\nimport { withTime, watch } from 'kefir-test-utils';\n\ndescribe('Kefir-test-utils example', () => {\n  it('should test a simple observable with virtual time', () => {\n    withTime((tick) => {\n      // Create a Kefir stream that emits 1, 2, 3 sequentially with 100ms intervals\n      const stream = Kefir.sequentially(100, [1, 2, 3]);\n      // Use `watch` to collect events from the stream\n      const watcher = watch(stream);\n\n      // Assert initial state\n      expect(watcher.next).toEqual([]);\n\n      // Advance virtual time\n      tick(50); // 50ms passed\n      expect(watcher.next).toEqual([]); // No emissions yet\n\n      tick(50); // Total 100ms passed\n      expect(watcher.next).toEqual([1]); // First emission received\n\n      tick(100); // Total 200ms passed\n      expect(watcher.next).toEqual([1, 2]); // Second emission received\n\n      tick(100); // Total 300ms passed\n      expect(watcher.next).toEqual([1, 2, 3]); // All emissions received\n      expect(watcher.complete).toEqual(true); // Stream completed\n    });\n  });\n\n  it('should handle errors in a stream gracefully', () => {\n    withTime((tick) => {\n      // Create a stream that emits 1, then an error, which is caught and mapped to a message\n      const errorStream = Kefir.sequentially(50, [1])\n        .concat(Kefir.later(50, new Error('Simulated Error')))\n        .flatMapErrors(e => Kefir.constant(e.message)); // Catch error and emit message\n\n      const watcher = watch(errorStream);\n\n      tick(50);\n      expect(watcher.next).toEqual([1]);\n\n      tick(50);\n      // The error was caught and its message was emitted as a 'next' event\n      expect(watcher.next).toEqual([1, 'Simulated Error']);\n      expect(watcher.error).toEqual([]); // No actual error was propagated by `flatMapErrors`\n      expect(watcher.complete).toEqual(true);\n    });\n  });\n});","lang":"typescript","description":"Demonstrates basic usage of `withTime` and `watch` to test a Kefir observable's emissions and completion over a virtual timeline, including how to handle and assert error scenarios."},"warnings":[{"fix":"Review existing tests, especially those with precise timing assertions or complex virtual time interactions, and adjust expectations if behavior subtly changes due to the underlying fake timer implementation's update.","message":"Version 2.0.0 includes an internal upgrade to its fake timers dependency, which might subtly alter timing behavior or test interaction patterns if previous versions relied on specific internal timer implementations. This could necessitate minor adjustments to tests with very precise timing assertions.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your project's Node.js environment is v12 or higher. Upgrade Node.js if necessary to avoid compatibility issues and leverage modern language features.","message":"Support for Node.js v10 has been dropped in version 2.0.0, aligning the library with more modern Node.js runtimes. Running on Node.js v10 or earlier will result in compatibility errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Install `kefir` in your project's dependencies: `npm install kefir` or `yarn add kefir`.","message":"The `kefir` package is a peer dependency of `kefir-test-utils`. It must be installed separately in your project alongside `kefir-test-utils` for the library to function correctly, as it provides the core observable primitives being tested.","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":"Install the 'kefir' package: `npm install kefir` or `yarn add kefir`.","cause":"The peer dependency 'kefir' is not installed in the project, which is required by `kefir-test-utils`.","error":"Error: Cannot find module 'kefir'"},{"fix":"For CommonJS environments, ensure you use `const { withTime } = require('kefir-test-utils');`. For ESM (recommended since v2.0.0), use `import { withTime } from 'kefir-test-utils';`.","cause":"This error typically indicates incorrect CommonJS `require` syntax when trying to access a named export, or attempting to use a default import for a named export in an ESM context.","error":"TypeError: (0, _kefirTestUtils.withTime) is not a function"}],"ecosystem":"npm"}