import TestDSL from './TestDSL'; /** * Incrementing counter to assign each test context a globally unique id. * @type {number} Counter that maintains globally unique id and increments each time * a new id is assigned */ let testContextCounter = 0; /** * Incrementing counter to assign each test a globally unique id. * @type {number} Counter that maintains globally unique id and increments each time * a new id is assigned */ let testCounter = 0; /** * Increment the testCounter and return the new value. Used * for assigning a new globally unique id to a test. * @returns {number} globally unique id assigned to each test */ function assignTestId() { testCounter += 1; return testCounter; } /** * Increment the testContextCounter and return the new value. Used * for assigning a new globally unique id to a test context. * @returns {number} globally unique id assigned to each test context */ function assignContextId() { testContextCounter += 1; return testContextCounter; } /** * Enum for operators that can be used when combining test properties with their * parents at definition time. * @readonly * @enum {String} ContextOperator */ const CONTEXT_OPERATORS = { /** Perform OR of test value with context chain values * */ OR: 'OR', }; /** * Class that provides imperative interface for defining tests. When defining tests * the declarative interface for this class, {@link TestDSL} should be use instead. */ class TestSuiteDefinition { /** * Creates a new TestSuiteDefinition * @param {TestSuite} testSuite - The {@link TestSuite} instance for which to * define tests for. * @param {Object} firebase - Object containing native and web firebase instances * @param {Object} firebase.native - Native firebase instance * @para {Object} firebase.web - Web firebase instance */ constructor(testSuite, firebase) { this.testSuite = testSuite; this.tests = {}; this.pendingTestIds = {}; this.focusedTestIds = {}; this.testContexts = {}; this.rootTestContextId = assignContextId(); this.rootTestContext = this._initialiseContext(this.rootTestContextId, { name: '', focus: false, pending: false, parentContextId: null, }); this.currentTestContext = this.rootTestContext; this._testDSL = new TestDSL(this, firebase); } /** * Get the instance of {@link TestDSL} used for declaratively defining tests * @returns {TestDSL} The TestDSL used for defining tests */ get DSL() { return this._testDSL; } /** * Add a function as a before hook to the current test context * @param {Function} callback - Function to add as before hook to current test context */ addBeforeHook(callback, options = {}) { this._addHook('before', callback, options); } /** * Add a function as a before each hook to the current test context * @param {Function} callback - Function to add as before each hook to current test * context */ addBeforeEachHook(callback, options = {}) { this._addHook('beforeEach', callback, options); } /** * Add a function as a after each hook to the current test context * @param {Function} callback - Function to add as after each hook to current test context */ addAfterEachHook(callback, options = {}) { this._addHook('afterEach', callback, options); } /** * Add a function as a after hook to the current test context * @param {Function} callback - Function to add as after hook to current test context */ addAfterHook(callback, options = {}) { this._addHook('after', callback, options); } /** * Add a function to the list of hooks matching hookName, for the current test context * @param {('before'|'beforeEach'|'afterEach'|'after')} hookName - The name of the hook to add the function to * @param {Function} callback - Function to add as a hook * @param {Object=} options - Hook configuration options * @private */ _addHook(hookName, callback, options = {}) { const hookAttribute = `${hookName}Hooks`; if (callback && typeof callback === 'function') { this.currentTestContext[hookAttribute] = this.currentTestContext[hookAttribute] || []; this.currentTestContext[hookAttribute].push({ callback, timeout: options.timeout || 15000, }); } else { testDefinitionError( `non-function value ${callback} passed to ${hookName} for '${ this.currentTestContext.name }'` ); } } /** * @typedef {Object} ContextOptions * @property {Boolean} [focused=undefined] - whether context is focused or not. * @property {Boolean} [pending=undefined] - whether context is pending or not. */ /** * @typedef {Object} TestOptions * @extends ContextOptions * @property {Number} [timeout=5000] - Number of milliseconds before test times out */ /** * Push a test context onto the context stack, making it the new current test context * @param {String} name - The name of the new context * @param {ContextOptions} options - Options for new context */ pushTestContext(name, options = {}) { const testContextId = assignContextId(); const parentContext = this.currentTestContext; this.currentTestContext = this._initialiseContext( testContextId, Object.assign({ name, parentContextId: parentContext.id }, options) ); } /** * Pop test context off the context stack, making the previous context the new * current context. */ popTestContext() { const { parentContextId } = this.currentTestContext; this.currentTestContext = this.testContexts[parentContextId]; } /** * Add a test to the current test context * @param {String} description - The new test's description * @param {ContextOptions} options - The options for the new test * @param {Function} testFunction - The function that comprises the test's body */ addTest(description, options, testFunction = undefined) { let _testFunction; let _options; if (testFunction) { _testFunction = testFunction; _options = options; } else { _testFunction = options; _options = {}; } if (_testFunction && typeof _testFunction === 'function') { // Create test const testId = assignTestId(); this._createTest(testId, { testContextId: this.currentTestContext.id, testSuiteId: this.testSuite.id, description: this._testDescriptionContextPrefix(this.currentTestContext) + description, func: _testFunction, timeout: _options.timeout || 5000, }); // Add tests to context this.currentTestContext.testIds.push(testId); if (_options.focus || this.currentTestContext.focus) { this.focusedTestIds[testId] = true; } if (_options.pending || this.currentTestContext.pending) { this.pendingTestIds[testId] = true; } } else { testDefinitionError(`Invalid test function for "${description}".`); } } /** * Get the prefix to prepend to a test to fully describe it. Any context that is * nested 2 or more deep, i.e. non the root context nor a child of the root context, * has its name recursively prepended to all tests in that context or contexts it * contains. This allows tests to be easily displayed in a LinkedList during viewing * and reporting the test suite. * @param {Object} contextProperties - Properties of current context * @param {Number} contextProperties.id - Id of context * @param {String} contextProperties.name - Name of context * @param {Number} contextProperties.parentContextId - Id of context's parent * @param {String} [suffix=''] - Accumulation of context prefixes so far. Starts empty * and collects context prefixes as it recursively calls itself to iterate up the * context tree. * @returns {String} Prefix to be prepended to current accumulative string of context * names * @private */ _testDescriptionContextPrefix({ id, name, parentContextId }, suffix = '') { if ( id === this.rootTestContextId || parentContextId === this.rootTestContextId ) { return suffix; } return this._testDescriptionContextPrefix( this.testContexts[parentContextId], `${name} ${suffix}` ); } /** * @typedef {Object} TestContext * @property {Number} id - Globally unique id * @property {String} name - Short description of context * @property {Boolean} [focus=false] - Whether context is focused * @property {Boolean} [pending=false] - Whether context is pending * @property {Number} [parentContextId=undefined] - Id of context that contains the current one * @property {Number[]} testIds - List of ids of tests to be run in current context * @property {Number} testSuiteId - Id of test suite test context is apart of */ /** * Create a context from options provided * @param {Number} testContextId - Id to assign to new context once it's created * @param {Object} options - options to use to create the context * @param {String} options.name - Name of context to create * @param {Boolean} options.focus - Whether context is focused or not * @param {Boolean} options.pending - Whether context is pending or not * @param {Number} [options.parentContextId=undefined] - Id of context's parent * @returns {TestContext} New test context once it has been initialised * @private */ _initialiseContext(testContextId, { name, focus, pending, parentContextId }) { const existingContext = this.testContexts[testContextId]; if (existingContext) { return existingContext; } const parentContext = this.testContexts[parentContextId]; const newTestContext = { id: testContextId, name, focus: this._incorporateParentValue( parentContext, 'focus', focus, CONTEXT_OPERATORS.OR ), pending: this._incorporateParentValue( parentContext, 'pending', pending, CONTEXT_OPERATORS.OR ), parentContextId, testIds: [], testSuiteId: this.testSuite.id, }; this.testContexts[testContextId] = newTestContext; return newTestContext; } /** * Recursively use an operator to consolidate a test's value with that of its test * context chain. * @param {TestContext} parentContext - Parent context to examine for its value * @param {String} attributeName - name of the attribute to use from parent * @param {*} value - Value of current context or test to use as one operand with * the parent context's value * @param {('OR')} operator - Operator to use to consolidate current value and * parent context's value * @returns {*} Consolidated value, encorporating context parents' values * @private */ _incorporateParentValue(parentContext, attributeName, value, operator) { if (!parentContext) { return value; } switch (operator) { case CONTEXT_OPERATORS.OR: return parentContext[attributeName] || value; default: throw new Error(`Unknown context operator ${operator}`); } } /** * Create a new test from the options provided and add it to the suite * @param {Number} testId - Unique id to give to the test * @param {Object} testAttributes - attributes to create the test with * @param {Number} testAttributes.testContextId - Id of context test belongs to * @param {String} testAttributes.description - Short description of the test * @param {Function} testAttributes.func - Function that comprises the body of the test * @param {Number} testAttributes.testSuiteId - Id of test suite test belongs to * @param {Number} testAttributes.timeout - Number of milliseconds before test times out * @returns {Test} New test matching provided options * @private */ _createTest( testId, { testContextId, description, func, testSuiteId, timeout } ) { const newTest = { id: testId, testContextId, description, func, testSuiteId, status: null, message: null, time: 0, timeout, }; this.tests[testId] = newTest; return newTest; } } /** * Log test definition error to the console with a message indicating the test * definition was skipped. * @param {String} error - Error message to include in message logged to the console */ function testDefinitionError(error) { console.error(`ReactNativeFirebaseTests.TestDefinitionError: ${error}`); console.error('This test was ignored.'); } export default TestSuiteDefinition;