Part 1 of 5 in our series on TestBox 7.1's 47 new assertions. Read the release announcement.

If you have ever tested that two collections contain "the same stuff, order doesn't matter," you already know the workaround: sort both arrays, compare them element by element, and hope nobody adds a duplicate. It works, but it isn't what you meant to write. You meant "these are the same set."

BoxLang has a native Set type. TestBox 7.1 gives it nine matchers that speak the language of set theory directly, so your specs read like the requirement instead of a workaround for one.

The nine matchers

Every one of them has a not counterpart (notToBeASet(), notToEqualSet(), and so on), and every one accepts an optional custom message as the last argument.

// Old way: sort, then compare
expect( arraySort( duplicate( userRoles ), "text" ) )
    .toBe( arraySort( duplicate( expectedRoles ), "text" ) );

// New way: say what you mean
expect( setOf( userRoles ) ).toEqualSet( setOf( expectedRoles ) );

A realistic example: permission checks

Here's a small service that resolves a user's effective permissions from their assigned roles, and a spec that puts the set matchers through their paces. Both files are self contained. Drop them anywhere on your BoxLang class path and run the spec.

PermissionService.bx (the SUT)

/**
 * Resolves the effective permission Set for a user based on their roles.
 */
class {

	// Static role -> permission map for this example
	variables.rolePermissions = {
		"viewer"    : setOf( "read" ),
		"editor"    : setOf( "read", "write" ),
		"admin"     : setOf( "read", "write", "delete", "manageUsers" ),
		"billing"   : setOf( "read", "invoice", "refund" )
	};

	/**
	 * Returns the union of all permissions granted by the given roles.
	 *
	 * @roles An array of role names
	 */
	function getPermissionsForRoles( array roles ){
		var result = setOf();
		for ( var roleName in arguments.roles ) {
			if ( variables.rolePermissions.keyExists( roleName ) ) {
				result = result.union( variables.rolePermissions[ roleName ] );
			}
		}
		return result;
	}

	/**
	 * True if the user's permission set fully covers the required set.
	 *
	 * @userPermissions Set of permissions the user currently has
	 * @required Set of permissions the action requires
	 */
	function canPerform( set userPermissions, set required ){
		return arguments.required.isSubsetOf( arguments.userPermissions );
	}

}

PermissionServiceSpec.bx (the spec)

/**
 * Set Expectations in action: permission resolution
 */
class extends="testbox.system.BaseSpec" {

	function run() {
		describe( "PermissionService", () => {
			beforeEach( () => {
				variables.service = new PermissionService();
			} );

			it( "grants exactly the permissions of a single role", () => {
				var perms = service.getPermissionsForRoles( [ "editor" ] );

				expect( perms ).toBeASet();
				expect( perms ).toEqualSet( setOf( "read", "write" ) );
			} );

			it( "unions permissions across multiple roles", () => {
				var perms = service.getPermissionsForRoles( [ "editor", "billing" ] );

				expect( perms ).toHaveUnion(
					setOf( "read", "write" ),
					setOf( "read", "write", "invoice", "refund" )
				);
			} );

			it( "admin permissions are a superset of editor permissions", () => {
				var adminPerms  = service.getPermissionsForRoles( [ "admin" ] );
				var editorPerms = service.getPermissionsForRoles( [ "editor" ] );

				expect( adminPerms ).toBeSupersetOf( editorPerms );
			} );

			it( "viewer and billing roles do not overlap on write access", () => {
				var viewerPerms  = service.getPermissionsForRoles( [ "viewer" ] );
				var writeOnly    = setOf( "write", "delete", "manageUsers" );

				expect( viewerPerms ).toBeDisjointFrom( writeOnly );
			} );

			it( "denies an action when required permissions exceed the user's set", () => {
				var userPerms = service.getPermissionsForRoles( [ "viewer" ] );
				var required  = setOf( "read", "write" );

				expect( service.canPerform( userPerms, required ) ).toBeFalse();
				expect( required ).notToBeSubsetOf( userPerms );
			} );

			it( "allows an action when required permissions are fully covered", () => {
				var userPerms = service.getPermissionsForRoles( [ "admin" ] );
				var required  = setOf( "read", "delete" );

				expect( service.canPerform( userPerms, required ) ).toBeTrue();
				expect( required ).toBeSubsetOf( userPerms );
			} );

		} );
	}

}

Run it with the TestBox CLI:

box testbox run runner=PermissionServiceSpec.bx

BoxLang only, for now

The Set type and its literal helper setOf() are native to BoxLang. These nine matchers ship in TestBox 7.1 for every engine, but they only have something to grapple with on BoxLang. If you're still on Lucee or Adobe CFML, this is one more reason to try BoxLang, testing your set logic is meaningfully simpler once the language itself understands sets.

Next up, Part 2: 14 matchers for BoxLang's native Range type, bounds, steps, clamping, and the pagination logic you're probably still writing by hand.

box install testbox@7.1.0

Full release notes | TestBox docs | BoxLang