Assertion Helper

Purpose

Help write better assertions that:

Clearly express expected behavior
Provide actionable error messages
Are easy to understand when they fail
Cover all edge cases
Are framework-appropriate

When to Use

Invoke this skill when:

Writing test assertions
Debugging failing tests
Improving test readability
Creating custom matchers
Teaching testing best practices

Instructions

Step 1: Choose the Right Assertion

Select assertion based on what you're testing:

Equality: Value comparison
Type: Data type checking
Truthiness: Boolean conditions
Existence: Null/undefined checks
Inclusion: Array/object membership
Exceptions: Error throwing
Async: Promise resolution/rejection

Step 2: Make It Specific

Use the most specific assertion available:

toBe(5) > toBeTruthy()
toEqual([1,2,3]) > toHaveLength(3)
toThrow('Invalid') > toThrow()

Step 3: Add Context

Provide helpful messages for failures:

typescript

expect(result, 'User should be authenticated after login').toBe(true);

Step 4: Test Edge Cases

Include assertions for:

Null/undefined
Empty values
Boundaries (min/max)
Invalid inputs

Assertion Patterns

Jest/Vitest

Equality Assertions

typescript

// Primitive values (===)
expect(result).toBe(5);
expect(result).toBe('hello');
expect(result).toBe(true);

// Objects/Arrays (deep equality)
expect(user).toEqual({
  name: 'John',
  age: 30
});

expect(array).toEqual([1, 2, 3]);

// Opposite
expect(result).not.toBe(null);
expect(array).not.toEqual([]);

Type Assertions

typescript

// Null/Undefined
expect(value).toBeNull();
expect(value).toBeUndefined();
expect(value).toBeDefined();

// Truthiness
expect(value).toBeTruthy();
expect(value).toBeFalsy();

// Type checks
expect(typeof result).toBe('string');
expect(Array.isArray(result)).toBe(true);
expect(result instanceof Error).toBe(true);

Number Assertions

typescript

// Comparison
expect(age).toBeGreaterThan(18);
expect(age).toBeGreaterThanOrEqual(18);
expect(age).toBeLessThan(100);
expect(age).toBeLessThanOrEqual(100);

// Floating point
expect(result).toBeCloseTo(0.3, 2); // Within 2 decimal places

// NaN check
expect(result).toBeNaN();

String Assertions

typescript

// Exact match
expect(text).toBe('Hello World');

// Contains
expect(text).toContain('Hello');

// Regex
expect(email).toMatch(/^[a-z]+@[a-z]+\.[a-z]+$/);

// Case insensitive
expect(text.toLowerCase()).toBe('hello');

Array/Object Assertions

typescript

// Array membership
expect(array).toContain(item);
expect(array).toContainEqual({ id: 1 });

// Array length
expect(array).toHaveLength(3);

// Object properties
expect(obj).toHaveProperty('name');
expect(obj).toHaveProperty('address.city', 'NYC');

// Partial object match
expect(user).toMatchObject({
  name: 'John',
  // Other properties ignored
});

// Empty checks
expect(array).toEqual([]);
expect(obj).toEqual({});

Function/Error Assertions

typescript

// Function called
expect(mockFn).toHaveBeenCalled();
expect(mockFn).toHaveBeenCalledTimes(2);
expect(mockFn).toHaveBeenCalledWith(arg1, arg2);
expect(mockFn).toHaveBeenLastCalledWith(arg1, arg2);

// Function throws
expect(() => throwError()).toThrow();
expect(() => throwError()).toThrow(Error);
expect(() => throwError()).toThrow('Error message');
expect(() => throwError()).toThrow(/error/i);

// Return value
expect(mockFn).toHaveReturnedWith(value);

Async Assertions

typescript

// Promise resolves
await expect(promise).resolves.toBe(value);
await expect(promise).resolves.toEqual({ data: 'value' });

// Promise rejects
await expect(promise).rejects.toThrow();
await expect(promise).rejects.toThrow('Error message');

// Async function
it('should fetch user', async () => {
  const user = await fetchUser(1);
  expect(user).toEqual({ id: 1, name: 'John' });
});

Python (pytest)

Basic Assertions

python

# Equality
assert result == 5
assert result != 0

# Identity
assert result is None
assert result is not None

# Boolean
assert is_valid
assert not is_invalid

# Membership
assert item in collection
assert item not in collection

# Type
assert isinstance(result, str)
assert isinstance(result, (int, float))  # Multiple types

Numeric Assertions

python

# Comparison
assert age > 18
assert age >= 18
assert age < 100
assert age <= 100

# Approximate (floating point)
import pytest
assert result == pytest.approx(0.3, abs=0.01)

# Math checks
import math
assert math.isnan(result)
assert math.isinf(result)

String Assertions

python

# Exact match
assert text == "Hello World"

# Contains
assert "Hello" in text

# Regex
import re
assert re.match(r'^[a-z]+@[a-z]+\.[a-z]+$', email)

# Case insensitive
assert text.lower() == "hello"

# Start/End
assert text.startswith("Hello")
assert text.endswith("World")

Collection Assertions

python

# List/Tuple
assert len(collection) == 3
assert collection == [1, 2, 3]
assert collection != []

# Set operations
assert set(collection) == {1, 2, 3}

# Dict
assert 'key' in dictionary
assert dictionary['key'] == 'value'
assert dictionary.get('key') == 'value'

Exception Assertions

python

# Exception raised
with pytest.raises(ValueError):
    raise_error()

# Exception message
with pytest.raises(ValueError, match="Invalid input"):
    raise_error()

# Exception details
with pytest.raises(ValueError) as exc_info:
    raise_error()
assert str(exc_info.value) == "Invalid input"
assert exc_info.type == ValueError

Custom Assertions

python

def assert_valid_user(user):
    """Custom assertion for user validation"""
    assert user is not None, "User should not be None"
    assert 'id' in user, "User should have an id"
    assert 'name' in user, "User should have a name"
    assert isinstance(user['id'], int), "User id should be int"
    assert len(user['name']) > 0, "User name should not be empty"

# Usage
assert_valid_user(result)

Go (testing)

Basic Assertions

import "testing"

// Equality
if result != expected {
    t.Errorf("Expected %v, got %v", expected, result)
}

// Boolean
if !isValid {
    t.Error("Expected isValid to be true")
}

// Nil check
if result == nil {
    t.Error("Expected result to not be nil")
}

Helper Functions

func assertEqual(t *testing.T, expected, actual interface{}) {
    t.Helper()
    if expected != actual {
        t.Errorf("Expected %v, got %v", expected, actual)
    }
}

func assertNoError(t *testing.T, err error) {
    t.Helper()
    if err != nil {
        t.Errorf("Expected no error, got %v", err)
    }
}

func assertError(t *testing.T, err error, message string) {
    t.Helper()
    if err == nil {
        t.Error("Expected error, got nil")
        return
    }
    if !strings.Contains(err.Error(), message) {
        t.Errorf("Expected error containing %q, got %q", message, err.Error())
    }
}

// Usage
func TestFunction(t *testing.T) {
    result, err := Function()
    assertNoError(t, err)
    assertEqual(t, "expected", result)
}

Best Practices

DO:

✅ Use the most specific assertion ✅ Test one thing per assertion ✅ Add descriptive messages ✅ Test both positive and negative cases ✅ Use custom matchers for repeated patterns ✅ Group related assertions

DON'T:

❌ Use generic assertions (toBeTruthy()) ❌ Multiple unrelated assertions in one test ❌ Assertion without context ❌ Test implementation details ❌ Ignore edge cases ❌ Rely on assertion order

Assertion Patterns

The Positive/Negative Pattern

typescript

// Test both that it works AND doesn't work wrong
it('should validate email', () => {
  expect(validate('test@example.com')).toBe(true);
  expect(validate('invalid')).toBe(false);
});

The Boundary Pattern

typescript

// Test edges of valid ranges
it('should accept ages between 0 and 120', () => {
  expect(isValidAge(0)).toBe(true);
  expect(isValidAge(120)).toBe(true);
  expect(isValidAge(-1)).toBe(false);
  expect(isValidAge(121)).toBe(false);
});

The Null/Undefined Pattern

typescript

// Always test null/undefined cases
it('should handle null input', () => {
  expect(process(null)).toBeNull();
});

it('should handle undefined input', () => {
  expect(process(undefined)).toBeUndefined();
});

The Error Message Pattern

typescript

// Verify error messages for debugging
it('should throw descriptive error', () => {
  expect(() => divide(10, 0))
    .toThrow('Cannot divide by zero');
});

The State Verification Pattern

typescript

// Verify state changes
it('should update state correctly', () => {
  const obj = new Counter();
  expect(obj.count).toBe(0);

  obj.increment();
  expect(obj.count).toBe(1);

  obj.decrement();
  expect(obj.count).toBe(0);
});

Custom Matchers

Jest Custom Matcher

typescript

expect.extend({
  toBeValidEmail(received: string) {
    const pass = /^[a-z]+@[a-z]+\.[a-z]+$/.test(received);
    return {
      pass,
      message: () =>
        pass
          ? `Expected ${received} not to be a valid email`
          : `Expected ${received} to be a valid email`
    };
  }
});

// Usage
expect('test@example.com').toBeValidEmail();

Pytest Custom Assertion

python

def assert_valid_email(email: str) -> None:
    """Assert that email is valid"""
    import re
    pattern = r'^[a-z]+@[a-z]+\.[a-z]+$'
    assert re.match(pattern, email), f"'{email}' is not a valid email"

# Usage
assert_valid_email('test@example.com')

Debugging Failed Assertions

Add Context

typescript

// Bad
expect(result).toBe(5);

// Good
expect(result, 'Should calculate correct total after discount').toBe(5);

Use Better Diff

typescript

// For objects, toEqual gives better diff than toBe
expect(user).toEqual({
  id: 1,
  name: 'John',
  age: 30
});

Break Down Complex Assertions

typescript

// Bad - hard to debug
expect(result).toEqual({ id: 1, name: 'John', address: { city: 'NYC' } });

// Good - easier to see what failed
expect(result.id).toBe(1);
expect(result.name).toBe('John');
expect(result.address.city).toBe('NYC');

Output Format

When providing assertion guidance:

## Assertions for ${TestCase}

**Testing**: ${whatIsBeingTested}

**Recommended Assertions**:
```${language}
${assertions}

Why:

${reason1}
${reason2}

Edge Cases to Test:

${edgeCase1}
${edgeCase2}


## Related Skills

- `test-pattern-library`: For complete test patterns
- `mock-generator`: For mocking dependencies
- `test-data-factory`: For test data generation
- `error-message-writer`: For better error messages

Search AI Tools

Install this agent skill to your Project

SKILL.md

Assertion Helper

Purpose

When to Use

Instructions

Step 1: Choose the Right Assertion

Step 2: Make It Specific

Step 3: Add Context

Step 4: Test Edge Cases

Assertion Patterns

Jest/Vitest

Equality Assertions

Type Assertions

Number Assertions

String Assertions

Array/Object Assertions

Function/Error Assertions

Async Assertions

Python (pytest)

Basic Assertions

Numeric Assertions

String Assertions

Collection Assertions

Exception Assertions

Custom Assertions

Go (testing)

Basic Assertions

Helper Functions

Best Practices

DO:

DON'T:

Assertion Patterns

The Positive/Negative Pattern

The Boundary Pattern

The Null/Undefined Pattern

The Error Message Pattern

The State Verification Pattern

Custom Matchers

Jest Custom Matcher

Pytest Custom Assertion

Debugging Failed Assertions

Add Context

Use Better Diff

Break Down Complex Assertions

Output Format