Smartass(ertions)

TypeScript-first test assertion functions with precise type narrowing via assertion signatures.

https://smartassertions.dev/

Installation

npm install -D @kensio/smartass

Type narrowing with assertion signatures

See TypeScript assertion functions / assertion signatures

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.

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;

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.

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

• assertArrayEmpty
• assertArrayEquals
• assertArrayIncludesAll
• assertArrayIncludes
• assertArrayLength
• assertArrayMinLength
• assertArrayNotEmpty
• assertArrayNotIncludes
• assertBufferEqual
• assertDirectoryExists
• assertFalse
• assertFileEquals
• assertFileExists
• assertFileIncludes
• assertFileNotIncludes
• assertIdentical
• assertInstanceOf
• assertMapSize
• assertNonNullable
• assertNotEqual
• assertNumberBetween
• assertNumberToNearest
• assertObjectEquals
• assertObjectHasProperty
• assertObjectMatches
• assertOneOf
• assertPathExists
• assertPathNotExists
• assertResponseStatus
• assertSetSize
• assertStringEndsWith
• assertStringIncludes
• assertStringLength
• assertStringMatches
• assertStringNotIncludes
• assertStringStartsWith
• assertThrowsErrorAsync
• assertThrowsErrorLike
• assertThrowsError
• assertTrue
• assertTypeBigInt
• assertTypeBoolean
• assertTypeFunction
• assertTypeNumber
• assertTypeNumeric
• assertTypeObject
• assertTypeString
• assertTypeSymbol
• assertTypeTypedArray
• assertUndefined
• assertUuidV4

Matcher functions

• emptyArray
• arrayIncludingAll
• arrayIncluding
• arrayOfLength
• arrayOfMinLength
• nonEmptyArray
• arrayNotIncluding
• bufferEqualTo
• instanceOf
• mapOfSize
• nonNullable
• numberBetween
• numberToNearest
• objectWithProperty
• oneOf
• responseOfStatus
• setOfSize
• stringEndingWith
• stringIncluding
• stringOfLength
• stringMatching
• stringNotIncluding
• stringStartingWith
• typeBigInt
• typeBoolean
• typeFunction
• typeNumber
• typeNumeric
• typeObject
• typeString
• typeSymbol
• typeTypedArray
• uuidV4

Optional lint rules

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

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

Response status suggestions include the response description used on failure:

assertIdentical(response.status, 200);
// suggested improvement:
assertResponseStatus(response, 200, await describeResponse(response));

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

ESLint

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

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

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

Oxlint

The @kensio/smartass/oxlint export is an Oxlint JS plugin. Register it under jsPlugins and turn the rule on:

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