# Smartass

> Smartass is a TypeScript assertion library for tests. Its assertion functions narrow the type of what they are given, so a value checked once stays narrowed for the rest of the test, and its matchers express the same checks as values. It is an npm package, @kensio/smartass.

Each link below is the plain markdown of one page. Drop the `llms.txt` from a link for the page itself: https://smartassertions.dev/assertions/assertArrayEquals/llms.txt is https://smartassertions.dev/assertions/assertArrayEquals/ as HTML.

## Assertion functions

- [assertArrayEquals](https://smartassertions.dev/assertions/assertArrayEquals/llms.txt): Assert that an array exactly equals the expected array, with type narrowing.
- [assertArrayIncludesAll](https://smartassertions.dev/assertions/assertArrayIncludesAll/llms.txt): Assert that an array includes all specified elements, with type narrowing.
- [assertArrayIncludes](https://smartassertions.dev/assertions/assertArrayIncludes/llms.txt): Assert that an array includes a specific element, with type narrowing.
- [assertArrayLength](https://smartassertions.dev/assertions/assertArrayLength/llms.txt): Assert that an array has exactly the expected length, with type narrowing.
- [assertArrayMinLength](https://smartassertions.dev/assertions/assertArrayMinLength/llms.txt): Assert that an array has at least the expected minimum length, with type narrowing.
- [assertArrayNotEmpty](https://smartassertions.dev/assertions/assertArrayNotEmpty/llms.txt): Assert that an array has at least one element, with type-narrowing.
- [assertBufferEqual](https://smartassertions.dev/assertions/assertBufferEqual/llms.txt): Assert that two buffers (TypedArrays) are equal, comparing element by element.
- [assertDirectoryExists](https://smartassertions.dev/assertions/assertDirectoryExists/llms.txt): Assert that a filesystem path exists and is a directory.
- [assertFalse](https://smartassertions.dev/assertions/assertFalse/llms.txt): Assert that a value is strictly false (not just falsy), with type-narrowing to the literal type false.
- [assertFileEquals](https://smartassertions.dev/assertions/assertFileEquals/llms.txt): Assert that a file's content exactly equals the expected content.
- [assertFileExists](https://smartassertions.dev/assertions/assertFileExists/llms.txt): Assert that a filesystem path exists and is a file.
- [assertFileIncludes](https://smartassertions.dev/assertions/assertFileIncludes/llms.txt): Assert that a file includes a given substring.
- [assertFileNotIncludes](https://smartassertions.dev/assertions/assertFileNotIncludes/llms.txt): Assert that a file does not include a given substring.
- [assertIdentical](https://smartassertions.dev/assertions/assertIdentical/llms.txt): Assert that a value is strictly identical to an expected value using ===, with type-narrowing.
- [assertInstanceOf](https://smartassertions.dev/assertions/assertInstanceOf/llms.txt): Assertion function that checks if a value is an instance of a given class, with type-narrowing.
- [assertMapSize](https://smartassertions.dev/assertions/assertMapSize/llms.txt): Assert that a Map has exactly the expected size, with type narrowing.
- [assertNonNullable](https://smartassertions.dev/assertions/assertNonNullable/llms.txt): Assert that a value is non-nullable, with type-narrowing.
- [assertNumberBetween](https://smartassertions.dev/assertions/assertNumberBetween/llms.txt): Assert that a numeric value is between min and max inclusive, with type-narrowing.
- [assertNumberToNearest](https://smartassertions.dev/assertions/assertNumberToNearest/llms.txt): Assert that a numeric value, when rounded to the nearest given increment, equals the expected value.
- [assertObjectEquals](https://smartassertions.dev/assertions/assertObjectEquals/llms.txt): Assert that two objects have the same own keys and deeply equal values, with type narrowing.
- [assertObjectHasProperty](https://smartassertions.dev/assertions/assertObjectHasProperty/llms.txt): Assert that an object has a certain named property.
- [assertObjectMatches](https://smartassertions.dev/assertions/assertObjectMatches/llms.txt): Assert that an object matches a partial deep object structure, with type-narrowing.
- [assertOneOf](https://smartassertions.dev/assertions/assertOneOf/llms.txt): Assert that a value is one of a set of expected values, with type-narrowing.
- [assertPathExists](https://smartassertions.dev/assertions/assertPathExists/llms.txt): Assert that a filesystem path exists.
- [assertPathNotExists](https://smartassertions.dev/assertions/assertPathNotExists/llms.txt): Assert that a filesystem path does not exist.
- [assertResponseStatus](https://smartassertions.dev/assertions/assertResponseStatus/llms.txt): Assert that a Response has a specific HTTP status code, with type narrowing.
- [assertSetSize](https://smartassertions.dev/assertions/assertSetSize/llms.txt): Assert that a Set has exactly the expected size, with type narrowing.
- [assertStringEndsWith](https://smartassertions.dev/assertions/assertStringEndsWith/llms.txt): Assert that a string ends with a given suffix, with type narrowing.
- [assertStringIncludes](https://smartassertions.dev/assertions/assertStringIncludes/llms.txt): Assert that a string includes a given substring, with type narrowing.
- [assertStringLength](https://smartassertions.dev/assertions/assertStringLength/llms.txt): Assert that a string has exactly the expected length, with type narrowing.
- [assertStringNotIncludes](https://smartassertions.dev/assertions/assertStringNotIncludes/llms.txt): Assert that a string does not include a given substring, with type narrowing.
- [assertStringStartsWith](https://smartassertions.dev/assertions/assertStringStartsWith/llms.txt): Assert that a string starts with a given prefix, with type narrowing.
- [assertThrowsErrorAsync](https://smartassertions.dev/assertions/assertThrowsErrorAsync/llms.txt): Assertion function that verifies an async function throws an error.
- [assertThrowsErrorLike](https://smartassertions.dev/assertions/assertThrowsErrorLike/llms.txt): Assertion function that verifies a given function throws something that appears to be an error.
- [assertThrowsError](https://smartassertions.dev/assertions/assertThrowsError/llms.txt): Assertion function that verifies a given function throws an error.
- [assertTrue](https://smartassertions.dev/assertions/assertTrue/llms.txt): Assert that a value is strictly true (not just truthy), with type-narrowing to the literal type true.
- [assertTypeBigInt](https://smartassertions.dev/assertions/assertTypeBigInt/llms.txt): Asserts that a value is a bigint, with type-narrowing.
- [assertTypeBoolean](https://smartassertions.dev/assertions/assertTypeBoolean/llms.txt): Assert that a value is of type boolean, with type-narrowing.
- [assertTypeFunction](https://smartassertions.dev/assertions/assertTypeFunction/llms.txt): Assert that a value is of type function, with type-narrowing.
- [assertTypeNumber](https://smartassertions.dev/assertions/assertTypeNumber/llms.txt): Assert that a value is of type number, with type-narrowing.
- [assertTypeNumeric](https://smartassertions.dev/assertions/assertTypeNumeric/llms.txt): Assert that a value is numeric (number or bigint), with type-narrowing.
- [assertTypeObject](https://smartassertions.dev/assertions/assertTypeObject/llms.txt): Assert that a value is of type object, with type-narrowing.
- [assertTypeString](https://smartassertions.dev/assertions/assertTypeString/llms.txt): Assert that a value is of type string, with type-narrowing.
- [assertTypeSymbol](https://smartassertions.dev/assertions/assertTypeSymbol/llms.txt): Assert that a value is of type symbol, with type-narrowing.
- [assertTypeTypedArray](https://smartassertions.dev/assertions/assertTypeTypedArray/llms.txt): Assert that a value is a TypedArray, with type-narrowing.
- [assertUndefined](https://smartassertions.dev/assertions/assertUndefined/llms.txt): Assert that a value is strictly undefined, with type-narrowing to the undefined type.
- [assertUuidV4](https://smartassertions.dev/assertions/assertUuidV4/llms.txt): Assert that a value is a UUID v4 string, with type-narrowing.

## Matchers

- [arrayIncludingAll](https://smartassertions.dev/matchers/arrayIncludingAll/llms.txt): Matcher for an array including all specified elements.
- [arrayIncluding](https://smartassertions.dev/matchers/arrayIncluding/llms.txt): Matcher for an array including a specific single element.
- [arrayOfLength](https://smartassertions.dev/matchers/arrayOfLength/llms.txt): Matcher for an array with exactly the expected length.
- [arrayOfMinLength](https://smartassertions.dev/matchers/arrayOfMinLength/llms.txt): Matcher for an array with at least the expected minimum length.
- [nonEmptyArray](https://smartassertions.dev/matchers/nonEmptyArray/llms.txt): Matcher for a non-empty array.
- [bufferEqualTo](https://smartassertions.dev/matchers/bufferEqualTo/llms.txt): Matcher for a TypedArray equal to an expected TypedArray, comparing byte by byte.
- [instanceOf](https://smartassertions.dev/matchers/instanceOf/llms.txt): Matcher for a value being an instance of a given class.
- [mapOfSize](https://smartassertions.dev/matchers/mapOfSize/llms.txt): Matcher for a Map with exactly the expected size.
- [nonNullable](https://smartassertions.dev/matchers/nonNullable/llms.txt): Matcher for a non-nullable value.
- [numberBetween](https://smartassertions.dev/matchers/numberBetween/llms.txt): Matcher for a numeric value between min and max inclusive.
- [numberToNearest](https://smartassertions.dev/matchers/numberToNearest/llms.txt): Matcher for a number that, when rounded to the nearest given increment, equals the expected value.
- [objectWithProperty](https://smartassertions.dev/matchers/objectWithProperty/llms.txt): Matcher for an object with a certain named property.
- [oneOf](https://smartassertions.dev/matchers/oneOf/llms.txt): Matcher for a value that is one of a set of expected values.
- [responseOfStatus](https://smartassertions.dev/matchers/responseOfStatus/llms.txt): Matcher for a Response with a specific HTTP status code.
- [setOfSize](https://smartassertions.dev/matchers/setOfSize/llms.txt): Matcher for a Set with exactly the expected size.
- [stringEndingWith](https://smartassertions.dev/matchers/stringEndingWith/llms.txt): Matcher for a string that ends with a given suffix.
- [stringIncluding](https://smartassertions.dev/matchers/stringIncluding/llms.txt): Matcher for a string that includes a given substring.
- [stringOfLength](https://smartassertions.dev/matchers/stringOfLength/llms.txt): Matcher for a string with exactly the expected length.
- [stringNotIncluding](https://smartassertions.dev/matchers/stringNotIncluding/llms.txt): Matcher for a string that does not include a given substring.
- [stringStartingWith](https://smartassertions.dev/matchers/stringStartingWith/llms.txt): Matcher for a string that starts with a given prefix.
- [typeBigInt](https://smartassertions.dev/matchers/typeBigInt/llms.txt): Matcher for a bigint value.
- [typeBoolean](https://smartassertions.dev/matchers/typeBoolean/llms.txt): Matcher for a boolean value.
- [typeFunction](https://smartassertions.dev/matchers/typeFunction/llms.txt): Matcher for a function value.
- [typeNumber](https://smartassertions.dev/matchers/typeNumber/llms.txt): Matcher for a number value.
- [typeNumeric](https://smartassertions.dev/matchers/typeNumeric/llms.txt): Matcher for a numeric value (number or bigint).
- [typeObject](https://smartassertions.dev/matchers/typeObject/llms.txt): Matcher for an object value.
- [typeString](https://smartassertions.dev/matchers/typeString/llms.txt): Matcher for a string value.
- [typeSymbol](https://smartassertions.dev/matchers/typeSymbol/llms.txt): Matcher for a symbol value.
- [typeTypedArray](https://smartassertions.dev/matchers/typeTypedArray/llms.txt): Matcher for a TypedArray value.
- [uuidV4](https://smartassertions.dev/matchers/uuidV4/llms.txt): Matcher for a UUID v4 string value.

## ESLint

- [Optional ESLint config](https://smartassertions.dev/eslint-config-rules/llms.txt): The @kensio/smartass package also exports an optional ESLint flat config that discourages less specific assertion usage.

## Oxlint

- [Optional Oxlint plugin](https://smartassertions.dev/oxlint-plugin-rules/llms.txt): The @kensio/smartass package also exports an optional Oxlint plugin that discourages less specific assertion usage.

## Optional

- [npm package](https://www.npmjs.com/package/@kensio/smartass): install and version history
- [Source repository](https://github.com/KensioSoftware/smartass): source, issues and the docblocks these pages are built from

---

# Smartass Assertion Functions

Source: https://smartassertions.dev/

Smartass is an npm package that provides type-narrowing assertion functions for TypeScript projects.

## Installation

```bash
npm install -D @kensio/smartass
```

## Type narrowing with assertion signatures

See
[TypeScript assertion functions / assertion signatures](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions)

The fluent `expect().toBe()` interface in Jest and Vitest is readable, but is
unable to provide type information to TypeScript and IntelliSense.

This library provides assertion functions with assertion signatures so that you
can benefit from the extra type information.

```typescript
import { assertNonNullable } from "@kensio/smartass";

const user: { name: string } | undefined = getUser();
assertNonNullable(user);
// TypeScript now knows user is neither null nor undefined,
// so no need for ? or ! operators.
const userName = user.name;
```

```typescript
import { assertOneOf } from "@kensio/smartass";

const status = getStatus();
assertOneOf(status, ["pending", "active", "completed"]);
// TypeScript now knows status is of type 'pending' | 'active' | 'completed'
```

## Composable type narrowing matchers

As well as the standalone assertion functions, you can also use type narrowing matcher functions to
compose an object structure.

```typescript
import {
  assertObjectMatches,
  arrayIncluding,
  oneOf,
  stringOfLength,
} from "@kensio/smartass";

const user = getUser();

assertObjectMatches(user, {
  role: oneOf(["admin", "editor", "viewer"]),
  tags: arrayIncluding("beta"),
  id: stringOfLength(8),
});

// TypeScript knows:
//   user.role is 'admin' | 'editor' | 'viewer'
//   user.tags is an array with at least one string element
//   user.id is a string of length 8 with safe indexing
```

This applies the same type narrowing effect as the assertion functions but in a composable object
structure.

## Assertion functions

- [`assertArrayEquals`](https://smartassertions.dev/assertions/assertArrayEquals/)
- [`assertArrayIncludesAll`](https://smartassertions.dev/assertions/assertArrayIncludesAll/)
- [`assertArrayIncludes`](https://smartassertions.dev/assertions/assertArrayIncludes/)
- [`assertArrayLength`](https://smartassertions.dev/assertions/assertArrayLength/)
- [`assertArrayMinLength`](https://smartassertions.dev/assertions/assertArrayMinLength/)
- [`assertArrayNotEmpty`](https://smartassertions.dev/assertions/assertArrayNotEmpty/)
- [`assertBufferEqual`](https://smartassertions.dev/assertions/assertBufferEqual/)
- [`assertDirectoryExists`](https://smartassertions.dev/assertions/assertDirectoryExists/)
- [`assertFalse`](https://smartassertions.dev/assertions/assertFalse/)
- [`assertFileEquals`](https://smartassertions.dev/assertions/assertFileEquals/)
- [`assertFileExists`](https://smartassertions.dev/assertions/assertFileExists/)
- [`assertFileIncludes`](https://smartassertions.dev/assertions/assertFileIncludes/)
- [`assertFileNotIncludes`](https://smartassertions.dev/assertions/assertFileNotIncludes/)
- [`assertIdentical`](https://smartassertions.dev/assertions/assertIdentical/)
- [`assertInstanceOf`](https://smartassertions.dev/assertions/assertInstanceOf/)
- [`assertMapSize`](https://smartassertions.dev/assertions/assertMapSize/)
- [`assertNonNullable`](https://smartassertions.dev/assertions/assertNonNullable/)
- [`assertNumberBetween`](https://smartassertions.dev/assertions/assertNumberBetween/)
- [`assertNumberToNearest`](https://smartassertions.dev/assertions/assertNumberToNearest/)
- [`assertObjectEquals`](https://smartassertions.dev/assertions/assertObjectEquals/)
- [`assertObjectHasProperty`](https://smartassertions.dev/assertions/assertObjectHasProperty/)
- [`assertObjectMatches`](https://smartassertions.dev/assertions/assertObjectMatches/)
- [`assertOneOf`](https://smartassertions.dev/assertions/assertOneOf/)
- [`assertPathExists`](https://smartassertions.dev/assertions/assertPathExists/)
- [`assertPathNotExists`](https://smartassertions.dev/assertions/assertPathNotExists/)
- [`assertResponseStatus`](https://smartassertions.dev/assertions/assertResponseStatus/)
- [`assertSetSize`](https://smartassertions.dev/assertions/assertSetSize/)
- [`assertStringEndsWith`](https://smartassertions.dev/assertions/assertStringEndsWith/)
- [`assertStringIncludes`](https://smartassertions.dev/assertions/assertStringIncludes/)
- [`assertStringLength`](https://smartassertions.dev/assertions/assertStringLength/)
- [`assertStringNotIncludes`](https://smartassertions.dev/assertions/assertStringNotIncludes/)
- [`assertStringStartsWith`](https://smartassertions.dev/assertions/assertStringStartsWith/)
- [`assertThrowsErrorAsync`](https://smartassertions.dev/assertions/assertThrowsErrorAsync/)
- [`assertThrowsErrorLike`](https://smartassertions.dev/assertions/assertThrowsErrorLike/)
- [`assertThrowsError`](https://smartassertions.dev/assertions/assertThrowsError/)
- [`assertTrue`](https://smartassertions.dev/assertions/assertTrue/)
- [`assertTypeBigInt`](https://smartassertions.dev/assertions/assertTypeBigInt/)
- [`assertTypeBoolean`](https://smartassertions.dev/assertions/assertTypeBoolean/)
- [`assertTypeFunction`](https://smartassertions.dev/assertions/assertTypeFunction/)
- [`assertTypeNumber`](https://smartassertions.dev/assertions/assertTypeNumber/)
- [`assertTypeNumeric`](https://smartassertions.dev/assertions/assertTypeNumeric/)
- [`assertTypeObject`](https://smartassertions.dev/assertions/assertTypeObject/)
- [`assertTypeString`](https://smartassertions.dev/assertions/assertTypeString/)
- [`assertTypeSymbol`](https://smartassertions.dev/assertions/assertTypeSymbol/)
- [`assertTypeTypedArray`](https://smartassertions.dev/assertions/assertTypeTypedArray/)
- [`assertUndefined`](https://smartassertions.dev/assertions/assertUndefined/)
- [`assertUuidV4`](https://smartassertions.dev/assertions/assertUuidV4/)

## Matcher functions

- [`arrayIncludingAll`](https://smartassertions.dev/matchers/arrayIncludingAll/)
- [`arrayIncluding`](https://smartassertions.dev/matchers/arrayIncluding/)
- [`arrayOfLength`](https://smartassertions.dev/matchers/arrayOfLength/)
- [`arrayOfMinLength`](https://smartassertions.dev/matchers/arrayOfMinLength/)
- [`nonEmptyArray`](https://smartassertions.dev/matchers/nonEmptyArray/)
- [`bufferEqualTo`](https://smartassertions.dev/matchers/bufferEqualTo/)
- [`instanceOf`](https://smartassertions.dev/matchers/instanceOf/)
- [`mapOfSize`](https://smartassertions.dev/matchers/mapOfSize/)
- [`nonNullable`](https://smartassertions.dev/matchers/nonNullable/)
- [`numberBetween`](https://smartassertions.dev/matchers/numberBetween/)
- [`numberToNearest`](https://smartassertions.dev/matchers/numberToNearest/)
- [`objectWithProperty`](https://smartassertions.dev/matchers/objectWithProperty/)
- [`oneOf`](https://smartassertions.dev/matchers/oneOf/)
- [`responseOfStatus`](https://smartassertions.dev/matchers/responseOfStatus/)
- [`setOfSize`](https://smartassertions.dev/matchers/setOfSize/)
- [`stringEndingWith`](https://smartassertions.dev/matchers/stringEndingWith/)
- [`stringIncluding`](https://smartassertions.dev/matchers/stringIncluding/)
- [`stringOfLength`](https://smartassertions.dev/matchers/stringOfLength/)
- [`stringNotIncluding`](https://smartassertions.dev/matchers/stringNotIncluding/)
- [`stringStartingWith`](https://smartassertions.dev/matchers/stringStartingWith/)
- [`typeBigInt`](https://smartassertions.dev/matchers/typeBigInt/)
- [`typeBoolean`](https://smartassertions.dev/matchers/typeBoolean/)
- [`typeFunction`](https://smartassertions.dev/matchers/typeFunction/)
- [`typeNumber`](https://smartassertions.dev/matchers/typeNumber/)
- [`typeNumeric`](https://smartassertions.dev/matchers/typeNumeric/)
- [`typeObject`](https://smartassertions.dev/matchers/typeObject/)
- [`typeString`](https://smartassertions.dev/matchers/typeString/)
- [`typeSymbol`](https://smartassertions.dev/matchers/typeSymbol/)
- [`typeTypedArray`](https://smartassertions.dev/matchers/typeTypedArray/)
- [`uuidV4`](https://smartassertions.dev/matchers/uuidV4/)

## Optional lint rules

The `@kensio/smartass` package also exports optional lint rules that discourage less specific
assertion usage. For example:

```typescript
assertIdentical(foo.length, 2);
// suggested improvement:
assertArrayLength(foo, 2);
```

The same suggestions are available for both ESLint and Oxlint, generated from a single table of
selectors, so the two report identically.

### [ESLint](https://smartassertions.dev/eslint-config-rules/)

```typescript
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";

import { smartassPreferSpecificAssertions } from "@kensio/smartass/eslint";

export default defineConfig(
  ...tseslint.configs.recommended,
  ...smartassPreferSpecificAssertions,
);
```

### [Oxlint](https://smartassertions.dev/oxlint-plugin-rules/)

```json
{
  "jsPlugins": [{ "name": "smartass", "specifier": "@kensio/smartass/oxlint" }],
  "rules": {
    "smartass/prefer-specific-assertions": "warn"
  }
}
```