kea-test-utils

library0.2.4jsnpmunverified

Kea Test Utilities (kea-test-utils) is a library designed to streamline the testing of Kea logic stores, offering a fluent API for asserting logic behavior in JavaScript and TypeScript environments. Currently at version 0.2.4, it is actively maintained and ships with TypeScript types, aligning with the Kea 3.x ecosystem. The package provides core utilities such as `expectLogic` and `partial`, enabling developers to dispatch actions and then assert against the resulting state changes and subsequent dispatched actions. A critical aspect of its usage involves integrating the `testUtilsPlugin` with Kea's `resetContext` function before each test to ensure a clean, isolated testing environment. This allows for precise control over the Kea context, preventing state leakage and ensuring reliable test results. Its primary differentiator is its deep integration with Kea's internal mechanisms, providing comprehensive tools for both querying recorded action history and awaiting new actions for verification, making it indispensable for robust Kea application testing.

testing

npm install kea-test-utils

github ↗package ↗

INSTALL

IMPORT

SIG · KEA-TEST-UTILS

kea-test-utils

testingjavascriptv0.2.4

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.

expectLogic

✓ import { expectLogic } from 'kea-test-utils'

✗ const { expectLogic } = require('kea-test-utils')

Used for fluent assertion of Kea logic actions and state. ESM is the standard for Kea 3.x.

partial

✓ import { partial } from 'kea-test-utils'

✗ import partial from 'kea-test-utils/partial'

Utility function for matching only a subset of object properties in `toMatchValues`. Named import is correct.

testUtilsPlugin

✓ import { testUtilsPlugin } from 'kea-test-utils'

✗ import testUtilsPlugin from 'kea-test-utils/plugin'

Must be passed to `resetContext` from 'kea' to enable action and state recording for testing. Named import is correct.

resetContext

✓ import { resetContext } from 'kea'

✗ import { resetContext } from 'kea-test-utils'

While critical for `kea-test-utils` setup, `resetContext` is imported directly from the `kea` package.

Demonstrates how to test a simple Kea logic using `expectLogic` to dispatch actions, match dispatched actions, and assert against the resulting state, including setup with `resetContext` and `testUtilsPlugin`.

import { kea, resetContext } from 'kea'; import { expectLogic, testUtilsPlugin, partial } from 'kea-test-utils'; interface CounterLogicState { count: number; } interface CounterLogicActions { increment: (amount: number) => { amount: number }; decrement: (amount: number) => { amount: number }; } const counterLogic = kea<CounterLogicState, CounterLogicActions>({ path: ['scenes', 'counter'], actions: { increment: (amount: number) => ({ amount }), decrement: (amount: number) => ({ amount }), }, reducers: { count: [ 0, { increment: (state, { amount }) => state + amount, decrement: (state, { amount }) => state - amount, }, ], }, }); describe('counterLogic', () => { beforeEach(() => { // Essential: Reset Kea's context and enable test utilities before each test resetContext({ plugins: [testUtilsPlugin] }); }); test('should increment the count', async () => { await expectLogic(counterLogic, () => { // Dispatch actions directly on the logic counterLogic.actions.increment(5); }) .toDispatchActions(['increment']) .toMatchValues({ count: 5 }); }); test('should decrement the count', async () => { await expectLogic(counterLogic, () => { counterLogic.actions.decrement(2); }) .toDispatchActions(['decrement']) .toMatchValues(partial({ count: 3 })); // Using partial to match only specific values }); test('should handle multiple actions', async () => { await expectLogic(counterLogic, () => { counterLogic.actions.increment(10); counterLogic.actions.decrement(3); }) .toDispatchActions([ 'increment', 'decrement' ]) .toMatchValues({ count: 7 }); }); });

Debug

Known issues

breakingUpgrading Kea from v1.x to v2.x or v3.x changed how plugins are handled, specifically making 'listeners' built-in. If you explicitly passed `listenersPlugin` to `resetContext({ plugins: [...] })` in Kea v1.x, you must remove it when upgrading to Kea v2.x/v3.x or Kea will throw an error about the plugin being imported twice, preventing tests from running.

fix

Remove `listenersPlugin` from the `plugins` array passed to `resetContext` in your test setup. It is now included by default in `kea`.

affects: >=2.0

gotchaFailure to call `resetContext({ plugins: [testUtilsPlugin] })` before each test can lead to global state leakage between tests, causing unreliable and inconsistent test results. Kea manages a global context that must be reset for proper test isolation.

fix

Ensure `resetContext({ plugins: [testUtilsPlugin] })` is called in a `beforeEach` hook in your test suite to guarantee a clean Kea context for every test.

affects: >=0.1

gotchaThe `expectLogic` utility relies on the `testUtilsPlugin` being loaded into Kea's context. If `testUtilsPlugin` is not included in the `plugins` array when calling `resetContext`, `expectLogic` will not be able to record actions or access the logic's internal state history, leading to test failures or unexpected behavior.

fix

Always include `testUtilsPlugin` in the `plugins` array when calling `resetContext` in your test setup: `resetContext({ plugins: [testUtilsPlugin] })`.

affects: >=0.1

breakingIn Kea 1.0, the default path for logic without an explicit path (or when not using the Babel plugin) changed from `kea.inline` to `kea.logic`. If your tests or application hardcoded `kea.inline` anywhere, this change will cause issues. While this change is in the core Kea library, it impacts how logic paths are resolved in test environments.

fix

Update any hardcoded references from `kea.inline` to the new default or explicitly set `defaultPath` using `resetContext({ defaultPath: ['kea', 'inline'] })` if the old behavior is required.

affects: >=1.0

Errors

Common errors & fixes

Error: Plugin 'listenersPlugin' was loaded twice.

The `listenersPlugin` was explicitly added to `resetContext({ plugins: [...] })` after upgrading to Kea v2.x or v3.x, where listeners are now built-in to the core `kea` package.

fix

Remove `listenersPlugin` from the `plugins` array in your `resetContext` call.

Error: `expectLogic` requires `testUtilsPlugin` to be enabled in `resetContext`.

The `testUtilsPlugin` was not included in the `plugins` array when `resetContext` was called, preventing `expectLogic` from initializing its recording mechanisms.

fix

Ensure `testUtilsPlugin` is passed to `resetContext` in your `beforeEach` hook: `resetContext({ plugins: [testUtilsPlugin] })`.

TypeError: Cannot read properties of undefined (reading 'actions') when trying to call logic.actions.someAction

The Kea logic might not have been properly mounted or initialized within the test context, or `resetContext` was not called, leading to an undefined logic instance. This can also happen if `resetContext` is called *after* logic instantiation.

fix

Verify that `resetContext({ plugins: [testUtilsPlugin] })` is called within a `beforeEach` hook and that your logic is instantiated or connected correctly *after* the context has been reset.

Upgrade

Version history

0.2.4latest on npm

Audit

Dependencies

kearequiredRuntime peer dependency for Kea logic stores, required for context management and logic definition.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/keajs/kea-test-utils ↗

packagehttps://www.npmjs.com/package/kea-test-utils ↗