https://github.com/stackbuilders/assertive-ts
A type-safe fluent assertion library written in TypeScript and inspired by Jest assertions and the popular AssertJ
https://github.com/stackbuilders/assertive-ts
assertions hacktoberfest hacktoberfest2022 hacktoberfest2023 testing testing-tools type-safety typescript
Last synced: 6 months ago
JSON representation
A type-safe fluent assertion library written in TypeScript and inspired by Jest assertions and the popular AssertJ
- Host: GitHub
- URL: https://github.com/stackbuilders/assertive-ts
- Owner: stackbuilders
- License: mit
- Created: 2020-05-15T22:03:31.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-24T20:49:44.000Z (7 months ago)
- Last Synced: 2025-03-31T14:11:14.769Z (6 months ago)
- Topics: assertions, hacktoberfest, hacktoberfest2022, hacktoberfest2023, testing, testing-tools, type-safety, typescript
- Language: TypeScript
- Homepage: https://stackbuilders.github.io/assertive-ts/
- Size: 8.01 MB
- Stars: 33
- Watchers: 22
- Forks: 2
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](#contributors-)
[](https://github.com/stackbuilders/assertive-ts/actions/workflows/ci.yml)
[](https://github.com/stackbuilders/assertive-ts/actions/workflows/release.yml)
[](https://github.com/stackbuilders/assertive-ts/actions/workflows/pages.yml)
[](https://www.npmjs.com/package/@assertive-ts/core)
[](https://www.npmjs.com/package/@assertive-ts/sinon)
[](https://github.com/stackbuilders/assertive-ts/blob/main/LICENSE)
[](https://snyk.io/test/github/stackbuilders/assertive-ts)
# Assertive.ts
A type-safe fluent assertion library written in TypeScript and inspired by [Jest](https://jestjs.io/docs/expect) assertions and the popular [AssertJ](https://assertj.github.io/doc/).
This library is designed to work in Node.js. It ships with a rich set of expressive and flexible matchers that allows chaining multiple assertions. Assertive.ts is framework agnostic and should be used with a test framework such as [Jest](/docs/jest-tutorial.md), [Mocha](/docs/mocha-tutorial.md), or Ava.
**🚨 BREAKING CHANGES:** Since v2, the `@stackbuilders/assertive-ts` package has been renamed to `@assertive-ts/core` so we can group other packages, such as plugins, into the same namespace. Check the [packages](#packages) section for more info.
## Type-safe library
A distinctive feature of Assertive.ts with other assertion libraries is that it leverages the TypeScript compiler to avoid type coercions and mismatches. It also infers the static type of the value you want to assert and provides you with intelligent matcher completion and signature help so that you can write code more quickly and correctly.
### Features
- Type safety and intelligent matcher completion
- Rich set of expressive and flexible matchers
- Concise, chainable interface inspired by AssertJ
- Works with any test runner and framework such as [Jest](/docs/jest-tutorial.md), [Mocha](/docs/mocha-tutorial.md), or Ava
- Well tested: more than 300 tests!
## Packages
For convenience, this library is split into packages grouped within the same namespace:
- **[assertive-ts/core](https://github.com/stackbuilders/assertive-ts/blob/main/packages/core/README.md):** Core functionalities, assertions applicable for any kind of application. This package is required for the [extension mechanism](https://github.com/stackbuilders/assertive-ts/blob/main/packages/core/README.md#extension-mechanism-%EF%B8%8F) (plugins). This package replaces the deprecated `stackbuilders/assertive-ts` package.
- **[assertive-ts/sinon](https://github.com/stackbuilders/assertive-ts/blob/main/packages/sinon/README.md):** Plugin to add matchers for [Sinon.js](https://sinonjs.org/) spies, stubs, mocks, and fakes.
## Usage
Using you favorite test runner, you just need to import the `expect` and test away! If you don't really agree with `expect` as the name of the assertion function, we provide a couple aliases, such as `assert` and `assertThat`.
```ts
import { expect } from "@assertive-ts/core";
describe("sum", () => {
it("returns the sum of two numbers", () => {
const result = sum(3, 2);
expect(result).toBeEqual(5);
});
});
```
To assert the opposite, you can simply use the `.not` modifier before the matcher:
```ts
expect(sum(1, 2)).not.toBeNull();
```
This library provides **fluent assertions**, which means you can chain multiple matcher functions to the same value under test:
```ts
expect("assertive-ts is awesome!")
.toStartWith("assertive-ts")
.not.toContain("unsafe")
.toEndWith("awesome!");
```
The matcher functions depend on the type of the value on the `expect`. If you're using TypeScript, the compiler will let you know if something is not available for that assertion:
```ts
// Boolean assertion
expect(isEven(2)).toBeTrue();
// String assertion
expect("foobar").toStartWith("foo");
// Number assertion
expect(sum(1, 2)).toBePositive();
// Error assertion
expect(new Error(errorMessage)).toHaveMessage(expectedError);
// Array assertion
const data = [1, 2, 3, 4]
expect(data).toMatchAll(x => x < 5);
expect(data).toBeEmpty()
// Date assertion
const date = new Date(2023, 12, 31);
expect(date).toBeAfter(new Date(2023, 12, 1));
expect(date).toBeBefore(new Date(2024, 1, 1));
// Object assertion
const objectData = {
key1: "test1",
key2: "test2",
};
expect(objectData).toContainKey("key1");
expect(objectData).toContainEntry(["key1", "test1"]);
expect(14).toEndWith("4");
^ ? type error: `toEndWith` does not exist in `NumberAssertion`
```
You can also assert over functions and asynchronous code, for example:
```ts
function verifyEnvVar(): void {
const { MY_ENV_VAR } = process.env;
if (!MY_ENV_VAR) {
throw new Error("Missing MY_ENV_VAR environment variable");
}
};
// assertion
expect(() => verifyEnvVar())
.toThrowError(Error)
.toHaveMessage("Missing MY_ENV_VAR environment variable");
expect(() => verifyEnvVar()).not.toThrow();
async function getData(): Promise {
const data = await requestApi();
if (!data) {
throw new Error("Data was not found");
}
return data;
}
// assertion
await expect(getData()).toBeRejected();
await expect(getData()).toBeResolved();
```
For a list of all [Core](https://github.com/stackbuilders/assertive-ts/blob/main/packages/core/README.md) matchers and extended documentation, you can refer to the [Core API documentation](https://stackbuilders.github.io/assertive-ts/docs/core/build/).
## Test Runner Integration
Assertive.ts works on any JavaScript test runner, in the Node.js environments. Below you can find some example of how to use it on some of the most common test runners:
- [Jest Integration](https://github.com/stackbuilders/assertive-ts/blob/main/docs/jest-tutorial.md)
- [Mocha Integration](https://github.com/stackbuilders/assertive-ts/blob/main/docs/mocha-tutorial.md)
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Jose Luis Leon
💻 🚇 🚧 📦 ⚠️
Byron Motoche
💻 ⚠️ 👀
Alejandro Vivanco
💻 ⚠️ 👀
David Villamarin
💻 ⚠️ 📖 👀
Alexander Mejía
💻 ⚠️
Christian Samaniego
📖 💻 ⚠️ 👀
Sebastián Estrella
🚇
Daniel Calle
🚇
Anthony Suárez
📖
Sebastian Avalos
👀
Ikko Eltociear Ashimine
📖
Edwin Hernández
💻 👀
Marialejandra Contreras
💻 👀
Suany Chalan
💻
Karla Quistanchala
👀
Spencer Scorcelletti
📖
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
## License
MIT, see [the LICENSE file](LICENSE).
## Contributing
Do you want to contribute to this project? Please take a look at our [contributing guidelines](/docs/CONTRIBUTING.md) to know how you can help us build it. You can also check the [development guide](/docs/development.md) for information about local setup and the release process.
---
[Check out our libraries](https://github.com/stackbuilders/) | [Join our team](https://www.stackbuilders.com/join-us/)