> For the complete documentation index, see [llms.txt](https://testbox.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://testbox.ortusbooks.com/digging-deeper/expectations/matchers.md).

# Matchers

The `toBe()` matcher represents an equality matcher much how an `$assert.isEqual()` behaves. Below are several of the most common matchers available to you. However, the best way to see which ones are available is to checkout the [API Docs](http://apidocs.ortussolutions.com/testbox/current).

```javascript
toBeTrue( [message] ) :  value to true
toBeFalse( [message] ) : value to be false
toBe( expected, [message] ) : Assert something is equal to each other, no case is required
toBeWithCase( expected, [message] ) : Expects with case
toBeNull( [message] ) : Expects the value to be null
toBeInstanceOf( class, [message] ) : To be the class instance passed
toMatch( regex, [message] ) : Matches a string with no case-sensitivity
toMatchWithCase( regex, [message] ) : Matches with case-sensitivity
toBeTypeOf( type, [message] ) : Assert the type of the incoming actual data, it uses the internal ColdFusion isValid() function behind the scenes, type can be array, binary, boolean, component, date, time, float, numeric, integer, query, string, struct, url, uuid plus all the ones from isValid()
toBe{type}( [message] ) : Same as above but more readable method name. Example: .toBeStruct(), .toBeArray()
toBeEmpty( [message] ) : Tests if an array or struct or string or query is empty
toHaveKey( key, [message] ) : Tests the existence of one key in a structure or hash map
toHaveDeepKey( key, [message] ) : Assert that a given key exists in the passed in struct by searching the entire nested structure
toHaveLength( length, [message] ) : Assert the size of a given string, array, structure or query
toThrow( [type], [regex], [message] );
toBeCloseTo( expected, delta, [datepart], [message] ) : Can be used to approximate numbers or dates according to the expected and delta arguments.  For date ranges use the datepart values.
toBeBetween( min, max, [message] ) : Assert that the passed in actual number or date is between the passed in min and max values
toInclude( needle, [message] ) : Assert that the given "needle" argument exists in the incoming string or array with no case-sensitivity, needle in a haystack anyone?
toIncludeWithCase( needle, [message] ) : Assert that the given "needle" argument exists in the incoming string or array with case-sensitivity, needle in a haystack anyone?
toBeGT( target, [message] ) : Assert that the actual value is greater than the target value
toBeGTE( target, [message] ) : Assert that the actual value is greater than or equal the target value
toBeLT( target, [message] ) : Assert that the actual value is less than the target value
toBeLTE( target, [message] ) : Assert that the actual value is less than or equal the target value
toBeTruthy( [message] ) : Assert the value is truthy: not false, not zero, not an empty string, not null
toBeFalsy( [message] ) : Assert the value is falsy: false, zero, an empty string or null
toBeSameInstanceAs( expected, [message] ) : Assert both references point at the very same object instance, not merely equal values
toHaveSize( expected, [message] ) : Assert the size of an array, struct, string or query. Alias of toHaveLength() reading more naturally for collections
toThrowMatching( predicate, [message] ) : Assert an exception is thrown AND that it satisfies the passed closure/lambda predicate
toIncludeAll( needles, [message] ) : Assert the target contains every one of the passed values
toIncludeAny( needles, [message] ) : Assert the target contains at least one of the passed values
toIncludeNone( needles, [message] ) : Assert the target contains none of the passed values
```

{% hint style="info" %}
Every matcher above has a negated counterpart via the [not operator](/digging-deeper/expectations/not-operator.md), for example `expect( x ).notToHaveSize( 3 )`.
{% endhint %}

## Truthiness: `toBeTruthy()` and `toBeFalsy()`

`toBeTrue()` and `toBeFalse()` require an actual boolean. `toBeTruthy()` and `toBeFalsy()` are looser, and are useful when a function returns "something or nothing" rather than a strict boolean.

{% tabs %}
{% tab title="BoxLang" %}

```java
expect( "hello" ).toBeTruthy()
expect( [ 1, 2 ] ).toBeTruthy()
expect( 1 ).toBeTruthy()

expect( "" ).toBeFalsy()
expect( 0 ).toBeFalsy()
expect( [] ).toBeFalsy()
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
expect( "hello" ).toBeTruthy();
expect( [ 1, 2 ] ).toBeTruthy();
expect( 1 ).toBeTruthy();

expect( "" ).toBeFalsy();
expect( 0 ).toBeFalsy();
expect( [] ).toBeFalsy();
```

{% endtab %}
{% endtabs %}

## Identity: `toBeSameInstanceAs()`

`toBe()` compares values. `toBeSameInstanceAs()` compares identity, which is what you want when asserting that a singleton really is a singleton, or that a factory handed back the cached object rather than a fresh one.

{% tabs %}
{% tab title="BoxLang" %}

```java
var a = getInstance( "UserService" )
var b = getInstance( "UserService" )

expect( a ).toBeSameInstanceAs( b )      // same object in memory
expect( a ).notToBeSameInstanceAs( {} )
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
var a = getInstance( "UserService" );
var b = getInstance( "UserService" );

expect( a ).toBeSameInstanceAs( b );      // same object in memory
expect( a ).notToBeSameInstanceAs( {} );
```

{% endtab %}
{% endtabs %}

## Size: `toHaveSize()`

Works on arrays, structs, strings and queries.

{% tabs %}
{% tab title="BoxLang" %}

```java
expect( [ 1, 2, 3 ] ).toHaveSize( 3 )
expect( { a : 1, b : 2 } ).toHaveSize( 2 )
expect( "TestBox" ).toHaveSize( 7 )
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
expect( [ 1, 2, 3 ] ).toHaveSize( 3 );
expect( { a : 1, b : 2 } ).toHaveSize( 2 );
expect( "TestBox" ).toHaveSize( 7 );
```

{% endtab %}
{% endtabs %}

## Exceptions: `toThrowMatching()`

`toThrow()` matches on exception type and a message regex. `toThrowMatching()` hands you the exception so you can assert anything about it.

{% tabs %}
{% tab title="BoxLang" %}

```java
expect( () => paymentService.charge( amount = -5 ) )
    .toThrowMatching( e => e.type == "InvalidAmount" && e.detail contains "negative" )
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
expect( function(){
    paymentService.charge( amount = -5 );
} ).toThrowMatching( function( e ){
    return e.type == "InvalidAmount" && e.detail contains "negative";
} );
```

{% endtab %}
{% endtabs %}

This is the escape hatch for exceptions whose interesting detail is not in the type or the message: a custom `extendedInfo` payload, an error code, a nested cause.

## Collections: `toIncludeAll()`, `toIncludeAny()`, `toIncludeNone()`

`toInclude()` checks for a single needle. These three check for several at once against arrays, lists and strings.

{% tabs %}
{% tab title="BoxLang" %}

```java
expect( [ "admin", "editor", "viewer" ] ).toIncludeAll( [ "admin", "editor" ] )
expect( [ "admin", "viewer" ] ).toIncludeAny( [ "admin", "superuser" ] )
expect( [ "viewer" ] ).toIncludeNone( [ "admin", "superuser" ] )
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
expect( [ "admin", "editor", "viewer" ] ).toIncludeAll( [ "admin", "editor" ] );
expect( [ "admin", "viewer" ] ).toIncludeAny( [ "admin", "superuser" ] );
expect( [ "viewer" ] ).toIncludeNone( [ "admin", "superuser" ] );
```

{% endtab %}
{% endtabs %}

Use `toIncludeNone()` to assert the absence of things that must never leak, which reads better than chaining several negated `toInclude()` calls:

{% tabs %}
{% tab title="BoxLang" %}

```java
expect( serializedUser ).toIncludeNone( [ "password", "salt", "apiToken" ] )
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
expect( serializedUser ).toIncludeNone( [ "password", "salt", "apiToken" ] );
```

{% endtab %}
{% endtabs %}

## Specialized Matcher Families

TestBox 7.1 adds three dedicated matcher families with their own pages:

* [Set Expectations](/digging-deeper/expectations/set-expectations.md) for BoxLang `Set` objects
* [Range Expectations](/digging-deeper/expectations/range-expectations.md) for BoxLang `Range` objects
* [Data Navigator Expectations](/digging-deeper/expectations/data-navigator.md) for asserting against deeply nested structures by path


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://testbox.ortusbooks.com/digging-deeper/expectations/matchers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.