npm package: @moyal/js-test
Description: A lightweight, dependency-free JavaScript testing utility. This project is framework-agnostic and usable in both browser and Node.js environments.
Author: Ilan Moyal
Latest version: 2.1.8

<!-- This README.md was autogenerated by script. Edit build/README.content.md instead, and run `nmp run generateReadme` -->

# moyal.js.test 

[![license](https://img.shields.io/npm/l/@moyal/js-test)](https://github.com/IlanMoyal/moyal.js.test/blob/main/LICENSE)
[![npm version](https://img.shields.io/npm/v/@moyal/js-test)](https://www.npmjs.com/package/@moyal/js-test)
[![jsDelivr CDN](https://data.jsdelivr.com/v1/package/npm/@moyal/js-test/badge)](https://www.jsdelivr.com/package/npm/@moyal/js-test)
[![minzipped size](https://badgen.net/bundlephobia/minzip/@moyal/js-test)](https://bundlephobia.com/package/@moyal/js-test)

A lightweight, dependency-free JavaScript testing utility. This project is framework-agnostic and usable in both browser and Node.js environments.

## Information
- **Current Version:** 2.1.8
- **Author:** Ilan Moyal
- **Website:** https://www.moyal.es
- **License:** MIT
- **NPM:** [https://www.npmjs.com/package/@moyal/js-test](https://www.npmjs.com/package/@moyal/js-test)
- **API Documentation:** [View online](https://IlanMoyal.github.io/moyal.js.test/)

## Table of Contents
- [Installation](#installation)
- [Importing](#importing)
- [Features](#features)
- [Quick Start](#quick-start)
- [Custom Logger Support](#custom-logger-support)
- [Exported Modules and Classes](#exported-modules-and-classes)
- [Version Access](#version-access)
- [Example files and test files](#example-files-and-test-files)
- [License](#license)
- [Author](#author)

<!-- CONTENT -->
## Installation

> npm install @moyal/js-test

## Importing

### In Node.js (ES Module)

```js
import { Test } from "@moyal/js-test";
```

### In Node.js (CommonJS)

```js
const { Test } = require("@moyal/js-test");
```

### In the Browser (ES Module via CDN)

```html
<!-- From jsDelivr CDN (minified version) -->
<script type="module">
  import "https://cdn.jsdelivr.net/npm/@moyal/js-test@2.1.8/dist/moyal.test.umd.min.js";
</script>

<!-- From jsDelivr CDN (non minified version with documentation) -->
<script type="module">
  import "https://cdn.jsdelivr.net/npm/@moyal/js-test@2.1.8/dist/moyal.test.umd.js";
</script>
```

Or using **unpkg**:

```html
<script type="module">
  import "https://unpkg.com/@moyal/js-test@2.1.8/dist/moyal.test.umd.min.js";
</script>
```

## Features

- Minimalistic test runner with zero dependencies.
- Works in both browser and Node.js environments.
- Fluent-style test groups for structured assertions.
- Rich console output with color-coded results and grouping.
- Lazy evaluation support for deferred execution (note: not true async test execution).
- Built-in assertion types: equality, throws, null/undefined checks, and sequence comparison.
- Utilities for test numbering and hierarchical auto-numbering.
- Pluggable logger interface with default support for:
  - Browser `console`
  - Node.js `console` with indentation and ANSI coloring
  - Fallback printer for unknown environments


## Quick Start

See also quick-start folder for the source code of the examples.

```js
import {MultiLevelAutoNumbering, TestGroup} from '@moyal/js-test';

new TestGroup("MLA Numbered Tests")
   .areNotEqual("Validate inequality", 1, 2)
	 .areEqual("Test strings", "foo", "foo")
   .groupStart("Nested test group")
	   .isFalse("This is lie", () => 1 == 2)
	   .areEqual("Test B2", "Hello World!", () => "Hello World!") 
	 .groupClose();
	 .areEqual("Test booleans", true, true)
	 .areEqual("Test C", 123, 123)
	 .run(true, new MultiLevelAutoNumbering());
```
In this quick start example:

- Test group enable chaining test calls, as well as creating nested test groups.
- Values, functions and lambda expressions are supported for both expected and actual.
- Test is delayed until run is called.
- Passing true to run, print results to the the console; false prints nothing; null or undefined prints only errors.
- Passing an instance of MultiLevelAutoNumbering auto enumerate the tests.

More examples can be found in examples and test/units.

## Custom Logger Support

Override console output with your custom logger:
```js
import {Test, LoggerBase} from '@moyal/js-test';
class MyLogger extends LoggerBase {
  /* implement logger methods */
  log(message, color, ...args) { /* ... */}
  info(message, color, ...args) { /* ... */ }
  warn(message, color, ...args) { /* ... */ }
  error(message, color, ...args) { /* ... */ }
  group(label, color) { /* ... */ }
  groupCollapsed(label, color) { /* ... */ }
  groupEnd() { /* ... */ }
}

Test.logger = new MyLogger();  
```

**Note**
The logger methods are chainable. 


## Exported Modules and Classes

### Testing types

- `Test` - Contains static method for testing.
- `TestBase` - Derive your class from TestBase to create custom test.
- `Assert` - Base class for assertions.
- `IsDefined` - Asserts that the specified evaluates to defined value.
- `IsUndefined` - Asserts that the specified evaluates to undefined value.
- `IsFalse` - Asserts that the specified evaluates to `false`.
- `IsTrue` - Asserts that the specified evaluates to `false`.
- `IsNull` - Asserts that the specified evaluates to `null`.
- `IsNotNull` - Asserts that the specified evaluates to non `null` value.
- `AreEqual` - Asserts that the specified values evaluations are equal.
- `AreNotEqual` - Asserts that the specified values evaluations are not equal.
- `ThrowsBase` - Base class to test error throwing.
- `Throws` - Asserts that the specified throws error.
- `NoThrows` - Asserts that the specified does not throw error.
- `SequencesAreEqual` - Asserts that the specified sequences are equal.
- `TestGroup` - Groups and enables chaining of multiple tests.

### Utility types:
- `SequentialText` - Utility class to generate sequential text.
- `AutoNumbering` - Utility class to generate automatic incremented number.
- `MultiLevelAutoNumbering` - Utility class to generate automatic incremented number.

### Logging types:
- `LoggerBase` - Base class for logger.
- `SimpleLogger` - Simple logger for unknown environments.
- `BrowserLogger` - Console logger for browser.
- `NodeLogger` - Console logger for NodeJS.

The namespace `MoyalTest` is also exported which wrapping all these types.

## Version Access

Access the library version directly:
```js
import * as myLib from "@moyal/js-test";

myLib.Version // → e.g., "2.1.8"
```

## Example files and test files

Example files can be found under `examples` folder and/or  `test/units` folder
(You can treat these test files as examples)


## License

MIT License - free to use, modify, and distribute.

## Author

**Ilan Moyal**
Website: [https://www.moyal.es](https://www.moyal.es)

GitHub: [Ilan Moyal](https://github.com/IlanMoyal)

LinkedIn: [Ilan Moyal](https://www.linkedin.com/in/ilanam)