describe(), it(), and getSuites() Function Reference

The three functions describe, it, and getSuites form the structural backbone of every test file. describe organises related tests under a named block, it registers an individual test case within that block, and getSuites retrieves the global list of all root suites so the runner can execute them. Suites are stored in a module-level array and persist for the lifetime of the script—calling describe multiple times simply appends to that list.

Type Definitions

Before diving into the functions, it helps to understand the core types they operate on.

Show TestFn

interface TestFn {
    (): void;
}

A zero-argument function that executes a test or hook. It must return void; any assertion failure is communicated by throwing an Error.

Show Test

interface Test {
    name: string;
    fn: TestFn;
}

name

string

required

The human-readable label for this test case, as passed to it().

TestFn

required

The function that contains the test body and assertions.

Show Suite

interface Suite {
    description: string;
    tests: Test[];
    children?: Suite[];
    parent?: Suite;
    beforeEach?: TestFn;
    afterEach?: TestFn;
    beforeAll?: TestFn;
    afterAll?: TestFn;
}

description

string

required

The label for this suite block, as passed to describe().

tests

Test[]

required

All test cases registered directly inside this describe block via it().

children

Suite[]

Nested describe blocks declared inside this suite. Populated automatically when a nested describe call is made while this suite is active.

parent

Suite

Reference to the enclosing Suite, or undefined for root suites.

beforeEach

TestFn

Hook registered via beforeEach(). Runs before every test in this suite (and is inherited by child suites).

afterEach

TestFn

Hook registered via afterEach(). Runs after every test in this suite (and is inherited by child suites).

beforeAll

TestFn

Hook registered via beforeAll(). Runs once before all tests in this specific suite.

afterAll

TestFn

Hook registered via afterAll(). Runs once after all tests in this specific suite.

describe()

function describe(description: string, fn: () => void): void

Creates a new test suite and immediately invokes its factory function fn. Any it(), beforeEach(), afterEach(), beforeAll(), or afterAll() calls made during the synchronous execution of fn are registered on that suite. Nested describe calls are supported and produce child suites linked via the parent / children references on Suite. Only root-level suites (those not nested inside another describe) are pushed into the global suites array that getSuites() returns. Child suites are reachable through the root’s children tree.

description

string

required

A human-readable label for the test suite. Appears in reporter output and is concatenated with child suite descriptions to build the full test name used for filtering.

() => void

required

A synchronous callback in which you register tests and hooks. The function is called immediately and must not be async.

Example

import { describe, it, expect } from 'kt-testing-suite-core';

describe('Array utilities', () => {
    it('returns the correct length', () => {
        expect([1, 2, 3]).toHaveLength(3);
    });

    it('identifies an array', () => {
        expect([]).toBeArray();
    });
});

Nesting describe blocks

describe('Math', () => {
    describe('addition', () => {
        it('adds two positive numbers', () => {
            expect(1 + 2).toBe(3);
        });
    });

    describe('subtraction', () => {
        it('subtracts correctly', () => {
            expect(5 - 3).toBe(2);
        });
    });
});

The fn callback is executed synchronously at the point describe is called. All suite registration happens at script parse time, before the runner is invoked.

it()

function it(name: string, fn: TestFn): void

Registers a single test case on the currently active suite. The test is not executed immediately—it is stored on the suite’s tests array and run later by the TestRunner.

name

string

required

The label for this test case. Combined with all ancestor suite descriptions (space-separated) to form the full test name that appears in reporter output and is matched against the runner’s filter string.

TestFn

required

The synchronous function that contains assertions. If this function throws any error the test is marked as failed; if it returns normally the test is marked as passed.

it() must be called inside a describe() block. Calling it at the top level of a script will throw:

Error: it() must be called inside a describe()

Example

describe('String checks', () => {
    it('detects a string type', () => {
        expect('hello').toBeString();
    });

    it('checks string content', () => {
        expect('hello world').toContain('world');
    });
});

getSuites()

function getSuites(): Suite[]

Returns the array of all root Suite objects registered so far. This is the same array that runTests() uses by default when no explicit suite list is provided.

getSuites() returns a live reference to the internal array. Suites are appended each time a top-level describe() executes. Typically you call this once at the end of your test file, after all describe blocks have been defined.

Return Value

Suite[]

An array of root Suite objects. Each suite may have nested child suites accessible via the children property. The array is ordered by registration time (first describe first).

Example

import { describe, it, getSuites, runTests } from 'kt-testing-suite-core';

describe('Feature A', () => {
    it('works', () => { /* ... */ });
});

describe('Feature B', () => {
    it('also works', () => { /* ... */ });
});

// Retrieve and inspect before running
const suites = getSuites();
$.writeln('Registered suites: ' + suites.length); // 2

// Pass to runner explicitly
runTests(suites);

You can also call runTests() with no arguments and it will call getSuites() internally. Passing getSuites() explicitly is useful when you want to filter or inspect the suite list before running.

Core API

describe(), it(), and getSuites() Function Reference

Type Definitions

describe()

Example

Nesting describe blocks

it()

Example

getSuites()

Return Value

Example

Build docs developers (and LLMs) love

Core API

Documentation Index

​Type Definitions

​describe()

​Example

​Nesting describe blocks

​it()

​Example

​getSuites()

​Return Value

​Example

Build docs developers (and LLMs) love

Type Definitions

describe()

Example

Nesting describe blocks

it()

Example

getSuites()

Return Value

Example