or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdconfiguration.mdexception-execution.mdindex.mdtest-assertions.mdtest-control.mdtest-creation.md
tile.json

test-creation.mddocs/

Test Creation

Core test creation functionality providing various test types and execution modes for comprehensive testing workflows.

Capabilities

Main Test Function

Creates a basic test that can run in callback mode or inverted (promise-based) mode.

/**
 * Create a test
 * @param name - Optional test name
 * @param options - Optional test configuration
 * @param callback - Optional test function for callback mode
 * @returns Test instance (inverted mode) or Promise<boolean> (callback mode)
 */
function test(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;

Usage Examples:

import test from "brittle";

// Callback mode
test("basic test", (t) => {
  t.is(2 + 2, 4);
});

// Inverted mode
const t = test("inverted test");
t.is(await getData(), "expected");
t.end();

// With options
test("timeout test", { timeout: 5000 }, (t) => {
  // Test with 5 second timeout
});

Solo Tests

Creates a test that runs in isolation, filtering out all other non-solo tests.

/**
 * Create a solo test (runs exclusively, skipping other tests)
 * @param name - Optional test name
 * @param options - Optional test configuration
 * @param callback - Optional test function for callback mode
 * @returns Test instance (inverted mode) or Promise<boolean> (callback mode)
 */
function solo(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;

/**
 * Enable solo mode globally
 * @returns void
 */
function solo(): void;

Usage Examples:

import { solo, test } from "brittle";

// Only this test will run
solo("focused test", (t) => {
  t.pass("only this runs");
});

// This will be skipped
test("regular test", (t) => {
  t.pass("this won't run");
});

// Enable solo mode globally
solo();

Skip Tests

Creates a test that is skipped during execution.

/**
 * Create a skipped test
 * @param name - Optional test name
 * @param options - Optional test configuration
 * @param callback - Optional test function (not executed)
 * @returns Promise<boolean>
 */
function skip(name?: string, options?: TestOptions, callback?: (t: Test) => void): Promise<boolean>;

Usage Examples:

import { skip } from "brittle";

skip("not ready yet", (t) => {
  t.pass("this won't execute");
});

skip("broken feature", { timeout: 1000 }, (t) => {
  // Test code that's temporarily disabled
});

Todo Tests

Creates a test marked as TODO, which is skipped but marked differently in output.

/**
 * Create a TODO test (skipped but marked as TODO)
 * @param name - Optional test name
 * @param options - Optional test configuration
 * @param callback - Optional test function (not executed)
 * @returns Promise<boolean>
 */
function todo(name?: string, options?: TestOptions, callback?: (t: Test) => void): Promise<boolean>;

Usage Examples:

import { todo } from "brittle";

todo("implement feature X", (t) => {
  // Placeholder for future test
});

todo("fix bug Y", (t) => {
  t.is(buggyFunction(), "expected result");
});

Hook Tests

Creates a test that always runs regardless of solo mode settings.

/**
 * Create a hook test (always runs, even in solo mode)
 * @param name - Optional test name
 * @param options - Optional test configuration
 * @param callback - Optional test function for callback mode
 * @returns Test instance (inverted mode) or Promise<boolean> (callback mode)
 */
function hook(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;

Usage Examples:

import { hook, solo } from "brittle";

// This always runs
hook("setup", (t) => {
  // Global setup code
  t.pass("setup complete");
});

// Even with solo tests, hook still runs
solo("focused test", (t) => {
  t.pass("solo test");
});

Stealth Tests

Creates a test that runs with minimal output (only summary, no individual assertions).

/**
 * Create a stealth test (minimal output mode)
 * @param name - Optional test name
 * @param options - Optional test configuration
 * @param callback - Optional test function for callback mode
 * @returns Test instance (inverted mode) or Promise<boolean> (callback mode)
 */
function stealth(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;

Usage Examples:

import { stealth } from "brittle";

stealth("quiet test", (t) => {
  t.is(1, 1); // Won't show individual assertion output
  t.pass("passed"); // Only test summary will show
});

// Inverted stealth mode
const t = stealth("stealth inverted");
t.ok(true);
t.end();

Test Options

interface TestOptions {
  /** Test timeout in milliseconds (default: 30000) */
  timeout?: number;
  /** Skip all other tests except solo ones */
  solo?: boolean;
  /** Always execute regardless of solo mode */
  hook?: boolean;
  /** Skip this test */
  skip?: boolean;
  /** Mark as TODO and skip */
  todo?: boolean;
  /** Only print test summary */
  stealth?: boolean;
}

Overload Patterns

All test creation functions support multiple calling patterns:

// Name only
test("test name", callback);

// Options only  
test({ timeout: 5000 }, callback);

// Name and options
test("test name", { timeout: 5000 }, callback);

// Inverted mode (no callback)
const t = test("test name", { timeout: 5000 });

// Minimal (just callback)
test(callback);