@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:

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

Basic Usage

`typescript
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>;

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

$3

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

$3

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

$3

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)

$3

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.

$3

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.

$3

Is not implemented yet.

Migration from Standard Deno Testing

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

Before:

`typescript
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:

`typescript
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!