or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

assert-interface.md configuration.md core-assertions.md expect-interface.md index.md plugin-system.md should-interface.md utilities.md

tile.json

Expect Interface

BDD-style assertions using the expect() function with chainable syntax for expressive and readable test statements. The expect interface is the most popular way to write assertions in Chai.

Capabilities

expect Function

Creates an assertion object that wraps the given value and provides chainable assertion methods.

/**
 * Creates an assertion object for the given value
 * @param value - The value to assert against
 * @param message - Optional custom error message
 * @returns Assertion instance for chaining
 */
function expect(value: any, message?: string): Assertion;

Usage Examples:

import { expect } from "chai";

// Basic assertions
expect(42).to.equal(42);
expect("hello").to.be.a("string");
expect(true).to.be.true;
expect([1, 2, 3]).to.have.lengthOf(3);

// With custom error messages
expect(value, "Value should be positive").to.be.above(0);

expect.fail

Throws an assertion error with optional context for explicit test failures.

/**
 * Throws an assertion error with optional context
 * @param actual - The actual value (optional)
 * @param expected - The expected value (optional)
 * @param message - Custom error message (optional)
 * @param operator - Comparison operator (optional)
 * @throws AssertionError
 */
expect.fail(actual?: any, expected?: any, message?: string, operator?: string): never;

Usage Examples:

// Simple failure
expect.fail("Something went wrong");

// Failure with actual/expected values
expect.fail(actual, expected, "Values don't match", "===");

// Failure with just message
if (condition) {
  expect.fail("Condition should not be true");
}

Common Assertion Patterns

Basic Value Assertions

// Equality
expect(42).to.equal(42);              // Non-strict equality (==)
expect(42).to.eql(42);                // Deep equality
expect("42").to.not.equal(42);        // Type-safe inequality

// Type checking
expect("hello").to.be.a("string");
expect(42).to.be.a("number");
expect([]).to.be.an("array");
expect({}).to.be.an("object");

// Truthiness
expect(true).to.be.true;
expect(false).to.be.false;
expect(1).to.be.ok;                   // Truthy
expect("").to.not.be.ok;              // Falsy

Comparison Assertions

// Numeric comparisons
expect(5).to.be.above(3);
expect(5).to.be.at.least(5);
expect(3).to.be.below(5);
expect(3).to.be.at.most(3);
expect(1.5).to.be.within(1, 2);
expect(1.5).to.be.closeTo(1.6, 0.2);

// String/Pattern matching
expect("hello world").to.match(/world/);
expect("hello world").to.include("world");
expect("hello world").to.have.string("world");

Object and Property Assertions

const obj = { name: "Alice", age: 25, active: true };

// Property existence
expect(obj).to.have.property("name");
expect(obj).to.have.property("age", 25);
expect(obj).to.have.nested.property("user.name");

// Property values
expect(obj).to.have.own.property("name");
expect(obj).to.include({ name: "Alice" });
expect(obj).to.deep.include({ name: "Alice", age: 25 });

// Keys
expect(obj).to.have.keys("name", "age", "active");
expect(obj).to.have.any.keys("name", "email");
expect(obj).to.contain.keys("name", "age");

Array and Collection Assertions

const array = [1, 2, 3, 4, 5];

// Length
expect(array).to.have.lengthOf(5);
expect(array).to.have.length.above(3);

// Members
expect(array).to.include(3);
expect(array).to.include.members([2, 4]);
expect(array).to.have.members([1, 2, 3, 4, 5]);
expect(array).to.have.ordered.members([1, 2, 3, 4, 5]);

// Deep member checking
expect([{a: 1}, {b: 2}]).to.deep.include({a: 1});
expect([{a: 1}, {b: 2}]).to.have.deep.members([{a: 1}, {b: 2}]);

Function Assertions

function throwsError() {
  throw new Error("Something went wrong");
}

function returnsValue() {
  return 42;
}

// Exception testing
expect(throwsError).to.throw();
expect(throwsError).to.throw(Error);
expect(throwsError).to.throw("Something went wrong");
expect(throwsError).to.throw(Error, /went wrong/);

// Function properties
expect(returnsValue).to.be.a("function");
expect(returnsValue).to.have.property("name", "returnsValue");

Advanced Patterns

// Chaining with and
expect(42)
  .to.be.a("number")
  .and.be.above(40)
  .and.be.below(50);

// Complex object validation
expect(user)
  .to.be.an("object")
  .that.has.property("name")
  .that.is.a("string")
  .and.has.length.above(0);

// Negation
expect("hello").to.not.equal("world");
expect([1, 2, 3]).to.not.include(4);
expect(obj).to.not.have.property("invalid");

// Deep equality with nested objects
expect({
  user: { name: "Alice", preferences: { theme: "dark" } }
}).to.have.nested.property("user.preferences.theme", "dark");

Error Handling

When assertions fail, expect provides detailed error messages:

// This will throw: AssertionError: expected 5 to equal 10
expect(5).to.equal(10);

// This will throw: AssertionError: Custom message: expected 5 to equal 10
expect(5, "Custom message").to.equal(10);

// This will show a diff for objects
expect({ a: 1, b: 2 }).to.deep.equal({ a: 1, b: 3 });
// AssertionError: expected { a: 1, b: 2 } to deeply equal { a: 1, b: 3 }
//   {
//     "a": 1,
// -   "b": 2
// +   "b": 3
//   }