@effectionx/bdd

A BDD (Behavior-Driven Development) testing harness for Deno that integrates seamlessly with Effection operations. This package provides a familiar describe/it/beforeEach API that works natively with Effection's generator-based operations.

Features

• 🔄 Native Effection Support: Test functions can be generator functions that yield operations
• 🏗️ Familiar BDD API: Uses the standard describe, it, and beforeEach functions you know and love
• 🧹 Automatic Cleanup: Proper resource management and cleanup for Effection operations
• 🎯 Skip and Only: Full support for .skip and .only modifiers
• 📦 Zero Configuration: Works out of the box with Deno's built-in testing framework

Installation

Add to your deno.json imports:

{
  "imports": {
    "@effectionx/bdd": "jsr:@effectionx/bdd"
  }
}

Basic Usage

import { beforeEach, describe, it } from "@effectionx/bdd";
import { expect } from "@std/expect";
import { sleep, spawn } from "effection";
import { createSignal, is } from "@effectionx/signals";

describe("My async operations", () => {
  let counter: ReturnType<typeof createSignal<number, void>>;

  beforeEach(function* () {
    // Setup that runs before each test
    counter = yield* createSignal(0);
    yield* sleep(10); // Can use Effection operations in setup
  });

  it("should increment counter", function* () {
    // Test function is a generator that can yield operations
    counter.update((n) => n + 1);
    yield* is(counter, (value) => value === 1);
    expect(counter.valueOf()).toBe(1);
  });
});

Real-World Examples

The following packages have been migrated to use @effectionx/bdd and provide excellent examples of testing patterns:

• stream-helpers: See batch.test.ts for testing stream batching with time and size limits
• signals: See array.test.ts for testing array signal operations like push, set, and update
• timebox: See timebox.test.ts for testing timeout scenarios with both success and timeout cases
• task-buffer: See task-buffer.test.ts for testing task queuing and buffer management
• websocket: See websocket.test.ts for testing bidirectional WebSocket communication and connection lifecycle
• worker: See worker.test.ts for testing web worker communication, error handling, and lifecycle management

Common Patterns Demonstrated

These test files show how to:

• Handle async operations without run() wrappers
• Test error scenarios using try/catch blocks instead of Promise rejections
• Use beforeEach for test setup with Effection operations
• Wait for signal changes using the is helper
• Test resource cleanup and proper teardown
• Handle timeouts and concurrent operations

API Reference

describe(name: string, body: () => void)

Creates a test suite with the given name. Test suites can be nested.

Options:

• describe.skip() - Skip this test suite
• describe.only() - Run only this test suite

it(desc: string, body?: () => Operation<void>)

Creates a test case with the given description. The body function should be a generator function that can yield Effection operations.

Options:

• it.skip() - Skip this test case
• it.only() - Run only this test case

Parameters:

• desc - Description of what the test should do
• body - Generator function containing the test logic (optional for pending tests)

beforeEach(body: () => Operation<void>)

Registers a setup function that runs before each test in the current suite. The body function should be a generator function that can yield Effection operations.

~~afterEach~~

This package doesn't include afterEach because it's typically used for clean up. With Effection, clean up is done in finally block of the resource. Consider creating a resource in beforeEach if you encounter a need for afterEach.

beforeAll

Is not implemented yet.

Migration from Standard Deno Testing

If you're migrating from standard Deno testing with Effection, the changes are minimal:

Before:

import { describe, it } from "@std/testing/bdd";
import { run } from "effection";

describe("my tests", () => {
  it("should work", async () => {
    await run(function* () {
      const result = yield* someOperation();
      expect(result).toBe("success");
    });
  });
});

After:

import { describe, it } from "@effectionx/bdd";
// No need to import 'run'

describe("my tests", () => {
  it("should work", function* () {
    const result = yield* someOperation();
    expect(result).toBe("success");
  });
});

Contributing

This package is part of the Effection ecosystem. Contributions are welcome!