Added lazy table row equals assertion

- Added `chai` and  extended with the `deep-equal-in-any-order` method.
- Created a lazy assertion comparitor `assertRowsEqualLazy` to compare tabel rows with expected rows, irrespective of order.
- Documented API according to the JSDoc markup.

package.json

@@ -36,6 +36,7 @@
 		"lib/**/*"
 	],
 	"devDependencies": {
+		"@types/chai": "^4.1.7",
 		"@types/mkdirp": "0.5.2",
 		"@types/mocha": "5.2.6",
 		"@types/node": "^11.13.4",
@@ -48,7 +49,9 @@
 	},
 	"dependencies": {
 		"axios": "0.18.0",
+		"chai": "^4.2.0",
 		"commander": "2.20.0",
+		"deep-equal-in-any-order": "^1.0.13",
 		"docker-cli-js": "2.5.2",
 		"glob": "7.1.3",
 		"mkdirp": "0.5.1",

src/utils.ts

@@ -1,8 +1,20 @@
 import * as assert from 'assert';
+import * as chai from 'chai';
+// @ts-ignore
+import * as deepEqualInAnyOrder from 'deep-equal-in-any-order';
 
 import { EOSManager } from './eosManager';
 import { TableRowsResult } from './contracts';
 
+// Exected Chai's expect methods
+chai.use(deepEqualInAnyOrder);
+
+/**
+ * Until Block
+ * @desc Pauses the current process until the specified EOS block number occurs
+ * @param number Process sleep duration
+ * @author Kevin Brown <github.com/thekevinbrown>
+ */
 export const untilBlockNumber = async (number: number) => {
 	let { head_block_num } = await EOSManager.rpc.get_info();
 
@@ -14,37 +26,91 @@ export const untilBlockNumber = async (number: number) => {
 	}
 };
 
+/**
+ * Sleep Process
+ * @desc Pauses the current process for the specified duration
+ * @param delayInMs Process sleep duration
+ * @author Kevin Brown <github.com/thekevinbrown>
+ */
 export const sleep = async (delayInMs: number) =>
 	new Promise(resolve => setTimeout(resolve, delayInMs));
 
+/**
+ * Next Block
+ * @desc Pauses the current process for the 500ms EOS block time
+ * @author Kevin Brown <github.com/thekevinbrown>
+ */
 export const nextBlock = () => sleep(500);
 
+/**
+ * Assert table rows equal expected
+ * @desc Compares table rows match expected rows
+ * @author Kevin Brown <github.com/thekevinbrown>
+ * @param getTableRowsResult Get table rows result promise
+ * @param expected Expected table row query results
+ */
 export const assertRowsEqual = async <RowType>(
 	getTableRowsResult: Promise<TableRowsResult<RowType>>,
 	expected: Array<RowType>
 ) => {
+	// Call the table row query and assert results equal expected
 	const result = await getTableRowsResult;
 	assert.deepEqual(result, {
 		rows: expected,
 		more: false,
 	});
 };
 
+/**
+ * Assert table rows eventually equal expected
+ * @desc Order irrespective comparison of table rows against expected rows
+ * @author Mitch Pierias <github.com/MitchPierias>
+ * @param getTableRowsResult Get table rows result promise
+ * @param expected Expected table row query results
+ */
+export const assertRowsEqualLazy = async <RowType>(
+	getTableRowsResult: Promise<TableRowsResult<RowType>>,
+	expected: Array<RowType>
+) => {
+	// Call table row query and assert results eventually equal expected
+	const result = await getTableRowsResult;
+	// @ts-ignore - Not sure how to add this extended method `equalInAnyOrder`?
+	chai.expect(result).to.deep.equalInAnyOrder({
+		rows: expected,
+		more: false,
+	});
+};
+
+/**
+ * Assert table row result count
+ * @desc Validates the number of rows returned is equal to the expected count
+ * @author Kevin Brown <github.com/thekevinbrown>
+ * @param getTableRowsResult Get table rows result promise
+ * @param expectedRowCount Expected number of table rows
+ */
 export const assertRowCount = async (
 	getTableRowsResult: Promise<TableRowsResult<any>>,
 	expectedRowCount: number
 ) => {
 	const result = await getTableRowsResult;
-
+	// Precheck table rows don't extend beyond returned result
 	assert.equal(
 		result.more,
 		false,
 		`There were more rows pending on the response which was not expected.`
 	);
-
+	// Validate the number of rows returned equals the expected count
 	assert.equal(result.rows.length, expectedRowCount, `Different number of rows than expected.`);
 };
 
+/**
+ * Assert EOS Error
+ * @desc Asserts EOS throws an error and validates the error output name matches the expected `eosErrorName`
+ * @author Kevin Brown <github.com/thekevinbrown>
+ * @param operation The operation result promise
+ * @param eosErrorName Expected EOS error name
+ * @param description Output message description
+ */
 export const assertEOSError = async (
 	operation: Promise<any>,
 	eosErrorName: string,
@@ -69,8 +135,20 @@ export const assertEOSError = async (
 	assert.fail(`Expected ${description} but operation completed successfully.`);
 };
 
-export const assertEOSAssert = (operation: Promise<any>) =>
+/**
+ * Assert EOS Exception
+ * @desc Asserts operation throws an `eosio_assert_message_exception` error
+ * @author Kevin Brown <github.com/thekevinbrown>
+ * @param operation The operation result promise
+ */
+export const assertEOSException = (operation: Promise<any>) =>
 	assertEOSError(operation, 'eosio_assert_message_exception', 'assert');
 
+/**
+ * Assert Missing EOS Authority
+ * @desc Asserts operation is missing the required authority by throwing a `missing_auth_exception` error
+ * @author Kevin Brown <github.com/thekevinbrown>
+ * @param operation The operation result promise
+ */
 export const assertMissingAuthority = (operation: Promise<any>) =>
 	assertEOSError(operation, 'missing_auth_exception', 'missing authority');