CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-japa--runner

A simple yet powerful testing framework for Node.js backend applications and libraries

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Japa Runner

Japa is a simple yet powerful testing framework specifically designed for Node.js backend applications and libraries. It offers a complete testing solution with a focus on simplicity, performance, and minimal bloat compared to frontend-oriented testing frameworks.

Package Information

  • Package Name: @japa/runner
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @japa/runner

Core Imports

import { test, configure, run } from "@japa/runner";

For additional functionality:

import { Test, Suite, Runner, Group, Emitter } from "@japa/runner/core";
import { spec, dot, ndjson, github } from "@japa/runner/reporters";
import { disallowPinnedTests } from "@japa/runner/plugins";
import { runner } from "@japa/runner/factories";
import type { Config, CLIArgs, PluginFn } from "@japa/runner/types";

For CommonJS:

const { test, configure, run } = require("@japa/runner");

Basic Usage

import { test, configure, run } from "@japa/runner";
import { assert } from "chai"; // or your preferred assertion library

// Configure the test runner
configure({
  files: ["tests/**/*.spec.ts"],
  forceExit: false,
});

// Define tests
test("should add two numbers", async (ctx) => {
  const result = 2 + 3;
  assert.equal(result, 5);
});

test.group("Math operations", (group) => {
  test("should subtract numbers", async (ctx) => {
    const result = 5 - 3;
    assert.equal(result, 2);
  });
});

// Run the tests
await run();

Architecture

Japa Runner is built around several key components:

  • Core Framework: Test execution engine with Suite, Runner, and Test classes
  • Configuration System: Flexible configuration with CLI argument processing and normalization
  • Plugin System: Extensible architecture supporting custom plugins for various testing scenarios
  • Reporter System: Multiple built-in reporters (spec, dot, ndjson, github) with custom reporter support
  • Hook System: Global setup/teardown hooks and test-level cleanup functions
  • Factory System: Test runner factory for testing reporters and plugins

Capabilities

Core Testing API

Primary API for creating and running tests with configuration, CLI processing, and execution management.

function test(title: string, callback?: TestExecutor<TestContext, undefined>): Test<undefined>;

function configure(options: Config): void;

async function run(): Promise<void>;

function processCLIArgs(argv: string[]): void;

Core Testing API

Test Management

Advanced test creation, grouping, and macro functionality for organizing complex test suites.

interface TestGroup {
  (title: string, callback: (group: Group) => void): Group;
}

interface TestMacro {
  <T extends (test: Test, ...args: any[]) => any>(callback: T): (...args: OmitFirstArg<Parameters<T>>) => ReturnType<T>;
}

function getActiveTest(): Test<any> | undefined;
function getActiveTestOrFail(): Test<any>;

Test Management

Configuration System

Comprehensive configuration options for test execution, filtering, and environment setup.

interface Config {
  cwd?: string;
  timeout?: number;
  retries?: number;
  filters?: Filters;
  configureSuite?: (suite: Suite) => void;
  reporters?: {
    activated: string[];
    list?: NamedReporterContract[];
  };
  plugins?: PluginFn[];
  forceExit?: boolean;
  setup?: SetupHookHandler[];
  teardown?: TeardownHookHandler[];
}

interface Filters {
  files?: string[];
  suites?: string[];
  tests?: string | string[];
  groups?: string | string[];
  tags?: string | string[];
}

Configuration System

Reporter System

Built-in reporters and reporter creation for test output formatting and result reporting.

function spec(options?: BaseReporterOptions): NamedReporterContract;
function dot(options?: BaseReporterOptions): NamedReporterContract;
function ndjson(options?: BaseReporterOptions): NamedReporterContract;
function github(options?: BaseReporterOptions): NamedReporterContract;

interface BaseReporterOptions {
  framesMaxLimit?: number;
}

Reporter System

Plugin System

Plugin architecture for extending functionality with built-in and custom plugins.

interface PluginFn {
  (japa: {
    config: NormalizedConfig;
    cliArgs: CLIArgs;
    runner: Runner;
    emitter: Emitter;
  }): void | Promise<void>;
}

function disallowPinnedTests(options?: {
  disallow?: boolean;
  errorMessage?: string;
}): PluginFn;

Plugin System

Core Classes

Low-level classes for advanced usage, testing frameworks, and plugin development.

class Runner {
  bail(toggle?: boolean): this;
  registerReporter(reporter: ReporterContract): void;
  getSummary(): RunnerSummary;
}

class Test<TestData = undefined> {
  throws(message: string | RegExp, errorConstructor?: any): this;
  timeout(duration: number): this;
  retry(count: number): this;
}

class TestContext {
  cleanup(cleanupCallback: TestHooksCleanupHandler<TestContext>): void;
}

Core Classes

Factory System

Test runner factory for testing reporters, plugins, and creating isolated test environments.

function runner(): RunnerFactory;

class RunnerFactory {
  configure(config: Config, argv?: string[]): this;
  useEmitter(emitter: Emitter): this;
  async runTest(title: string, callback: TestExecutor<TestContext, undefined>): Promise<RunnerSummary>;
  bail(toggle?: boolean): this;
  async runSuites(suites: (emitter: Emitter, refiner: Refiner, file?: string) => Suite[]): Promise<RunnerSummary>;
}

Factory System

Types

Core Configuration Types

interface CLIArgs {
  _?: string[];
  tags?: string | string[];
  files?: string | string[];
  tests?: string | string[];
  groups?: string | string[];
  timeout?: string;
  retries?: string;
  reporters?: string | string[];
  forceExit?: boolean;
  failed?: boolean;
  help?: boolean;
  matchAll?: boolean;
  listPinned?: boolean;
  bail?: boolean;
  bailLayer?: string;
}

type TestFiles = string | string[] | (() => URL[] | Promise<URL[]>);

interface TestSuite {
  name: string;
  files: TestFiles;
  configure?: (suite: Suite) => void;
  timeout?: number;
  retries?: number;
}

Hook Types

type SetupHookHandler = HookHandler<[runner: Runner], [error: Error | null, runner: Runner]>;
type TeardownHookHandler = HookHandler<[runner: Runner], [error: Error | null, runner: Runner]>;

interface HooksEvents {
  setup: [[runner: Runner], [error: Error | null, runner: Runner]];
  teardown: [[runner: Runner], [error: Error | null, runner: Runner]];
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@japa/runner@4.4.x
Publish Source
CLI
Badge
tessl/npm-japa--runner badge