diff options
Diffstat (limited to 'longbow/src/LongBow/longBow_TestFixture.h')
| -rw-r--r-- | longbow/src/LongBow/longBow_TestFixture.h | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/longbow/src/LongBow/longBow_TestFixture.h b/longbow/src/LongBow/longBow_TestFixture.h new file mode 100644 index 00000000..926f3e03 --- /dev/null +++ b/longbow/src/LongBow/longBow_TestFixture.h @@ -0,0 +1,274 @@ +/* + * Copyright (c) 2017 Cisco and/or its affiliates. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at: + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file longBow_TestFixture.h + * @ingroup internals + * @brief Manage the execution of Test Cases. + * + * A Test Fixture manages the individual execution of Test Cases. + * + */ +#ifndef LongBowTestFixture_H_ +#define LongBowTestFixture_H_ + +#include <string.h> + +struct longbow_fixture; + +/** + * @typedef LongBowTestFixture + * @brief The LongBow Test Fixture. + * + * This structure is created and initialized by the LongBow Test Runner. + * When the Test Fixture represented by this structure is executed, + * this structure is updated with the results of each LongBow Test Case that belongs to this Fixture. + */ +typedef struct longbow_fixture LongBowTestFixture; + +#include <LongBow/longBow_ClipBoard.h> +#include <LongBow/longBow_TestRunner.h> +#include <LongBow/longBow_TestCase.h> +#include <LongBow/longBow_TestFixtureConfig.h> + +typedef void (LongBowTestFixtureFunction)(const LongBowTestRunner *testRunner, const LongBowTestFixture *testFixture); + +typedef int (LongBowTestFixtureSetupFunction)(const LongBowTestRunner *, const LongBowTestFixture *, const LongBowTestCase *, LongBowClipBoard *); + +typedef int (LongBowTestFixtureTearDownFunction)(const LongBowTestRunner *, const LongBowTestFixture *, const LongBowTestCase *, LongBowClipBoard *); + +/** + * @typedef LongBowTestFixtureSummary + * @brief The summary for a test fixture. + */ +typedef struct longbow_fixture_summary { + /** + * The total number of test cases executed. + */ + unsigned int totalTested; + /** + * The number of test cases that succeeded. + */ + unsigned int totalSucceeded; + /** + * The number of test cases that failed. + */ + unsigned int totalFailed; + /** + * The number of test cases that were skipped. + */ + unsigned int totalSkipped; + /** + * The number of test cases that issued a warning. + */ + unsigned int totalWarned; + /** + * The number of test cases that setup failed. + */ + unsigned int totalSetupFailed; + /** + * The number of test cases that failed due to an signal. + */ + unsigned int totalSignalled; + /** + * The number of test cases that failed due to a stop signal. + */ + unsigned int totalStopped; + /** + * The number of test cases in which the tear-down failed. + */ + unsigned int totalTearDownFailed; + /** + * The number of test cases in which the tear-down issued a warning. + */ + unsigned int totalTearDownWarned; + /** + * The number of test cases that existed but indicated they were unimplemented. + */ + unsigned int totalUnimplemented; +} LongBowTestFixtureSummary; + +/** + * Update the summary information from the given LongBowTestCase. + * + * @param testCase A pointer to a valid LongBowTestCase instance. + */ +void longBowTestFixture_UpdateSummary(LongBowTestCase *testCase); + +/** + * + * @param testFixture A pointer to a valid LongBowTestFixture instance. + * @param testCase A pointer to a valid LongBowTestCase instance. + */ +void longBowTestFixture_AddTestCase(const LongBowTestFixture *testFixture, LongBowTestCase *testCase); + +/** + * + * @param testFixture A pointer to a valid LongBowTestFixture instance. + * @param index The index of the instance to get. + * @return A pointer to the LongBowTestCase instance at the given index. + */ +LongBowTestCase *longBowTestFixture_GetTestCase(const LongBowTestFixture *testFixture, size_t index); + +/** + * + * @param testFixture A pointer to a valid LongBowTestFixture instance. + * @return A pointer ot the LongBowTestRunner instance of the given LongBowTestFixture. + */ +LongBowTestRunner *longBowTestFixture_GetRunner(const LongBowTestFixture *testFixture); + +/** + * + * @param testFixture A pointer to a valid LongBowTestFixture instance. + * @return A pointer to the C string of the name of the given LongBowTestFixture. + */ +const char *longBowTestFixture_GetName(const LongBowTestFixture *testFixture); + +/** + * + * @param testFixture A pointer to a valid LongBowTestFixture instance. + * @return The number of LongBow Test Cases in the given LongBowTestFixture. + */ +size_t longBowTestFixture_GetTestCaseCount(const LongBowTestFixture *testFixture); + +/** + * Initialise a {@link LongBowTestFixture} structure with the given parameters. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @param [in] fixtureName The name of this Test Fixture. + * @param [in] setup A pointer to the function to call before invoking the first Test Case. + * @param [in] fixtureFunction A pointer to the function to call that will run each Test Case. + * @param [in] tearDown A pointer to the function to call after invoking the last Test Case. + * @return A pointer to an allocated LongBowTestFixture instance that must be deallocated via LongBowTestFixture_Destroy. + */ +LongBowTestFixture *longBowTestFixture_Create(const LongBowTestRunner *testRunner, + const char *fixtureName, + LongBowTestFixtureSetupFunction *setup, + LongBowTestFixtureFunction *fixtureFunction, + + LongBowTestFixtureTearDownFunction *tearDown); + +/** + * Destroy a LongBowTestFixture structure. + * + * @param fixturePtr A pointer to a LongBowTestFixture structure pointer. + */ +void longBowTestFixture_Destroy(LongBowTestFixture **fixturePtr); + +/** + * Get the fully qualified name of the given `LongBowTestFixture`. + * + * @param [in] testFixture A pointer to a valid LongBowTestCase instance. + * + * @return A constant nul-terminated, C string. + */ +const char *longBowTestFixture_GetFullName(const LongBowTestFixture *testFixture); + +void longBowTestFixture_ConfigHelp(void); + +bool longBowTestFixture_Config(LongBowConfig *config, const char *parameter); + +/** + * Execute a LongBow Test Fixture. + * + * The Test Fixture will execute Test Cases in the order they appear in the Test Fixture function. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @param [in] fixtureName The name of this Test Fixture. + * @param [in] config A pointer to a LongBowTestFixtureConfig to use when running the Test Fixture. + * @param [in] setup A pointer to the function to call before invoking the first Test Case. + * @param [in] fixtureRun A pointer to the function to call that will run each Test Case. + * @param [in] tearDown A pointer to the function to call after invoking the last Test Case. + * @return An allocated structure representing this Test Fixture. + * + * Example: + * @code + * <#example#> + * @endcode + * + * @see LONGBOW_TEST_FIXTURE + */ +LongBowTestFixture *longBowTestFixture_Run(const LongBowTestRunner *testRunner, + const char *fixtureName, + const LongBowTestFixtureConfig *config, + LongBowTestFixtureSetupFunction *setup, + LongBowTestFixtureFunction *fixtureRun, + LongBowTestFixtureTearDownFunction *tearDown); + +/** + * Get the status of the given LongBow Test Fixture. + * + * @param testFixture A pointer to a valid LongBowTestFixture instance. + * @return The `LongBowStatus` of the given Test Fixture. + */ +LongBowStatus longBowTestFixture_GetStatus(const LongBowTestFixture *testFixture); + +/** + * Return <code>true</code> if the given test case was successful. + * + * @param testFixture A pointer to a valid LongBowTestFixture instance. + * @return `true` if the given test case was successful. + */ +bool longBowTestFixture_IsSuccessful(const LongBowTestFixture *testFixture); + +/** + * Get a pointer to {@link LongBowTestFixtureSummary} for the given Test Fixture. + * + * @param testFixture A pointer to a valid LongBowTestFixture instance. + * @return A pointer to {@link LongBowTestFixtureSummary} for the given Test Fixture. + */ +const LongBowTestFixtureSummary *longBowTestFixture_GetSummary(const LongBowTestFixture *testFixture); + +/** + * Perform a test case setup. + * + * @param [in] testFixture A pointer to a valid LongBowTestFixture instance. + * @param [in] testCase A pointer to a valid LongBowTestCase instance. + * @return The `LongBowStatus` returned from the setup function. + */ +LongBowStatus longBowTestFixture_Setup(LongBowTestFixture *testFixture, LongBowTestCase *testCase); + +/** + * Perform a test case teardown. + * + * @param testFixture A pointer to a valid LongBowTestFixture instance. + * @param [in] testCase A pointer to a valid LongBowTestCase instance. + * @return The `LongBowStatus` returned from the teardown function. + */ +LongBowStatus longBowTestFixture_TearDown(LongBowTestFixture *testFixture, LongBowTestCase *testCase); + +/** + * Get the clipboard that belongs to the given Test Fixture. + * + * Every LongBow test fixure has an associated "clipboard" that is specific to that fixture and + * is shared between the test runner setup and tear down functions. + * Test Runner setup may store things on the test fixture's clipboard, + * the test fixture may access them and the tear down destroy them. + * + * @param [in] testFixture A pointer to a valid LongBowTestFixture instance. + * @return The `LongBowTestCaseClipBoard` for the given `LongBowTestFixture`. + * + * @see longBowTestCase_GetClipBoard + */ +LongBowClipBoard *longBowTestFixture_GetClipBoard(const LongBowTestFixture *testFixture); + +/** + * Compose a C string representing the current state of the given `LongBowTestFixture`. + * + * @param [in] testFixture A pointer to a valid LongBowTestFixture instance. + * @return An allocated, nul-terminated C string that must be deallocated via free(3) + */ +char *longBowTestFixture_ToString(const LongBowTestFixture *testFixture); +#endif // LongBowTestFixture_H_ |