chai-smart-assert

Advanced Chai plugin for smart contract testing with Web3.js.

Features

• 🔢 Smart BigNumber comparisons - Automatically handles BN, hex strings, numbers, and decimal strings
• 📊 Deep array equality - Compares arrays with mixed BigNumber/number/string values
• 🔄 Async self-invoked setup - Automatic plugin initialization
• 📡 Event assertions - Chainable event verification for smart contract transactions
• 💰 Balance utilities - Built-in helpers for token and ETH balance checks
• ⚡ Revert expectations - Simple revert reason validation
• 🎯 Web3.js integration - Seamless work with utils.toBN(), toNumber(), hex conversions

Installation

npm install chai-smart-assert

Quick Start

Basic Setup

import web3Pkg from 'web3';
const { utils } = web3Pkg;
import _ from 'lodash';
import chai from 'chai';
import chaiAsPromised from 'chai-as-promised';
import chain from 'chai-smart-assert';

// Setup chai with plugins
chai.use(chain);
chai.use(chaiPlugin);
chai.should();

export const getBalance = async addr => utils.toBN(await web3.eth.getBalance(addr));

Comparison Methods

The plugin adds smart comparison capabilities to Chai's assertions:

.eq(value) - Smart Equality Assertion Automatically handles type conversions between:

BigNumber instances (web3.utils.BN)

Hexadecimal strings (0x...)

Decimal strings

Numbers

Arrays of mixed types

import { expect } from 'chai';

// BigNumber comparisons
const balance1 = utils.toBN('1000000000000000000');
const balance2 = utils.toBN('1000000000000000000');
expect(balance1).to.eq(balance2);

// Hex vs BigNumber
const hexValue = '0xde0b6b3a7640000';  // 1e18 in hex
const bnValue = utils.toBN('1000000000000000000');
expect(hexValue).to.eq(bnValue);  // ✅ passes - converts internally

// Number vs BigNumber
expect(1000000000000000000).to.eq(bnValue);  // ✅ passes

// Array of mixed types
const results = [
  utils.toBN('1000000000000000000'),
  '0xde0b6b3a7640000',
  1000000000000000000
];
const expected = [
  utils.toBN('1000000000000000000'),
  utils.toBN('1000000000000000000'),
  utils.toBN('1000000000000000000')
];
expect(results).to.eq(expected);  // ✅ deep equality with smart conversion

Smart Contract Testing Examples

Token Transfer Testing

import chai from 'chai';
const { expect } = chai;

describe('Token Contract', () => {
  let token;
  let owner;
  let recipient;

  it('should transfer tokens correctly', async () => {
    const initialOwnerBalance = await token.balanceOf(owner);
    const initialRecipientBalance = await token.balanceOf(recipient);
    const transferAmount = utils.toBN('1000000000000000000');

    await token.transfer(recipient, transferAmount, { from: owner });

    const finalOwnerBalance = await token.balanceOf(owner);
    const finalRecipientBalance = await token.balanceOf(recipient);

    // Smart comparison handles BN automatically
    expect(finalOwnerBalance).to.eq(initialOwnerBalance.sub(transferAmount));
    expect(finalRecipientBalance).to.eq(initialRecipientBalance.add(transferAmount));
  });
});

Multi-value Return Testing

it('should return multiple values correctly', async () => {
  const [balance, allowance, decimals] = await token.getDetailedInfo(owner);
  
  // Array comparison with mixed types
  const expected = [
    utils.toBN('5000000000000000000'),
    utils.toBN('0'),
    18
  ];
  
  expect([balance, allowance, decimals]).to.eq(expected);
});

API Reference

.eq(value)

Performs deep equality with automatic type conversion.

Parameter Type Description value any The value to compare against. Supports BN, string, number, array, object Returns: Chai assertion object (chainable)

Throws: AssertionError when values don't match

Balance Helper Utilities (Recommended) While not included directly, the plugin pairs well with:

// Helper function example
export const getBalance = async addr => utils.toBN(await web3.eth.getBalance(addr));

// Usage in tests
await expect(getBalance(vaultAddress))
  .to.eventually.eq(utils.toBN('1000000000000000000'));

Why chai-smart-assert?

Testing smart contracts often involves:

BigNumber comparisons - Native JS === fails with BN objects

Mixed type arrays - Return values from contracts combine numbers, strings, and BNs

Hex vs decimal - Events log hex, balances are often decimal strings

This plugin solves these pain points by adding intelligent type coercion to Chai's eq assertion - no need to manually convert every value before comparison.

License

MIT

Contributing

Contributions welcome! Please submit issues and PRs on GitHub.