From ec688b4723a041044226358bcd4dd6e2da39da49 Mon Sep 17 00:00:00 2001 From: Luca Muscariello Date: Thu, 23 Feb 2017 17:01:02 +0100 Subject: Initial commit: cframework. Longbow and Libparc Change-Id: I90378dbd30da6033b20fb1f829b3b822cf366c59 Signed-off-by: Luca Muscariello --- longbow/src/LongBow/longBow_TestRunner.h | 269 +++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 longbow/src/LongBow/longBow_TestRunner.h (limited to 'longbow/src/LongBow/longBow_TestRunner.h') diff --git a/longbow/src/LongBow/longBow_TestRunner.h b/longbow/src/LongBow/longBow_TestRunner.h new file mode 100644 index 00000000..d787a17c --- /dev/null +++ b/longbow/src/LongBow/longBow_TestRunner.h @@ -0,0 +1,269 @@ +/* + * 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_TestRunner.h + * @ingroup testing + * @brief LongBow Test Runner Support. + * + */ +#ifndef LONGBOWRUNNER_H_ +#define LONGBOWRUNNER_H_ + +#include + +struct LongBowTestRunner; +/** + * @typedef LongBowRunner + * @brief The LongBow Test Runner + */ +typedef struct LongBowTestRunner LongBowRunner; + +typedef struct LongBowTestRunner LongBowTestRunner; + +#include +#include +#include +#include + +/** + * The function prototype for a LongBow Test Runner set-up function. + * + * @param testRunner A pointer to the associated LongBowTestRunner. + * @return A LongBowStatus value indicating the result of the set-up. + */ +typedef LongBowStatus (LongBowTestRunnerSetUp)(LongBowTestRunner *testRunner); + +/** + * The function prototype for a LongBow Test Runner function. + * + * @param testRunner A pointer to the associated LongBowTestRunner. + */ +typedef void (LongBowTestRunnerRun)(LongBowTestRunner *testRunner); + +/** + * The function prototype for a LongBow Test Runner tear-down function. + * + * @param testRunner A pointer to the associated LongBowTestRunner. + * @return A LongBowStatus value indicating the result of the tear-down. + */ +typedef LongBowStatus (LongBowTestRunnerTearDown)(LongBowTestRunner *testRunner); + +/** + * Allocate and initialise a LongBowTestRunner structure with the given parameters. + * + * See longBowTestRunner_Destroy to destroy the result. + * + * The parameters may be static values (ie. not allocated) supplied by the caller + * and they are not subject to free in longBowTestRunner_Destroy. + * + * @param [in] name The name of the LongBow test runner as a null-terminated string. + * @param [in] setup The setup function for the Test Runner + * @param [in] testRunner The function to call to execute the Test Runner. + * @param [in] tearDown The function to call to tear-down the Test Runner. + * @return An allocated LongBowTestRunner structure representing a Test Runner. + */ +LongBowTestRunner *longBowTestRunner_Create(const char *name, + LongBowTestRunnerSetUp *setup, + LongBowTestRunnerRun *testRunner, + LongBowTestRunnerTearDown *tearDown); + +/** + * Destroy a previously allocated LongBowTestRunner structure. + * + * @param [in,out] testRunnerPtr A pointer to a previously allocated LongBowTestRunner structure. + */ +void longBowTestRunner_Destroy(LongBowTestRunner **testRunnerPtr); + +/** + * Get the name of the given LongBowTestRunner. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @return The name of the Test Runner. + */ +const char *longBowTestRunner_GetName(const LongBowTestRunner *testRunner); + +/** + * Get the `LongBowClipBoard` for the given LongBowTestRunner. + * + * Every LongBow test case has an associated "clipboard" that is specific to a test case + * and is shared between the fixture setup and tear down functions. + * Fixture setup may store things on the clipboard, + * the test case may access them and the tear down destroy them. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @return The LongBowClipBoard for the given LongBowTestCase. + */ +LongBowClipBoard *longBowTestRunner_GetClipBoard(const LongBowTestRunner *testRunner); + +/** + * Place a value on the Test Runner "clipboard" + * + * Every Test Runner has an associated "clipboard" which is shared between the Test Runner + * Setup and Test Runner Tear Down and is accessible to all Test Fixtures and Test Cases. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @param [in] shared The value to share on the clipboard. + * @return True if the value was set. + */ +bool longBowTestRunner_SetClipBoardData(const LongBowTestRunner *testRunner, void *shared); + +/** + * Get the clipboard data from the given `LongBowTestRunner`. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + */ +void *longBowTestRunner_GetClipBoardData(const LongBowTestRunner *testRunner); + +/** + * Execute a LongBow Test Runner. + * + * The Test Runner will have zero or more Test Fixtures executed in the order + * they are specified in the Test Runner function. + * See LONGBOW_TEST_RUNNER() + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @return The given LongBowTestRunner + */ +LongBowTestRunner *longBowTestRunner_Run(LongBowTestRunner *testRunner); + +/** + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @return An allocated, nul-terminated C string that must be deallocated via free(3) + */ +char *longBowTestRunner_ToString(const LongBowTestRunner *testRunner); + +/** + * Add the supplied LongBowTestFixture to the list of Test Fixtures for the given Test Runner. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @param [in] testFixture A pointer to a valid LongBowTestFixture instance. + */ +void longBowTestRunner_AddFixture(LongBowTestRunner *testRunner, LongBowTestFixture *testFixture); + +/** + * Get the number of Test Fixtures in the given Test Runner. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @return the number of Test Fixtures in the given Test Runner. + */ +size_t longBowTestRunner_GetFixtureCount(const LongBowTestRunner *testRunner); + +/** + * Get a pointer to the Test Fixture indexed by index in this Test Runner. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @param [in] index The index of the LongBowTestFixture to get. + * @return The corresponding LongBowTestFixture. + */ +LongBowTestFixture *longBowTestRunner_GetFixture(const LongBowTestRunner *testRunner, size_t index); + +/** + * Get the status of the given LongBow Test Fixture. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @return The LongBowStatus of the given LongBowTestRunner + */ +LongBowStatus longBowTestRunner_GetStatus(const LongBowTestRunner *testRunner); + +/** + * Get a pointer to the LongBowConfig structure for the given Test Runner. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @return A pointer to the LongBowConfig structure for the given runner. + */ +LongBowConfig *longBowTestRunner_GetConfiguration(const LongBowTestRunner *testRunner); + +/** + * Return `true` if the given Test Runner was successful. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @return true if the status of the LongBowTestRunner was successful. + */ +bool longBowTestRunner_IsSuccessful(const LongBowTestRunner *testRunner); + +/** + * Return `true` if the given Test Runner was a failure. + * + * @param [in] testCase A pointer to a valid LongBowTestCase instance. + * @return true if the status of the LongBowTestRunner is as a failure. + */ +bool longBowTestRunner_IsFailed(const LongBowTestCase *testCase); + +/** + * Return `true` if the given Test Runner was a warning. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @return true if the status of the LongBowTestRunner was a warning. + */ +bool longBowTestRunner_IsWarning(const LongBowTestRunner *testRunner); + +/** + * Return `true` if the given Test Runner was incomplete. + * + * @param [in] testCase A pointer to a valid LongBowTestCase instance. + * @return true if the status of the LongBowTestRunner was incomplete. + */ +bool longBowTestRunner_IsIncomplete(const LongBowTestCase *testCase); + +/** + * Get the LongBowClipBoard for the given LongBowTestRunner. + * + * Every LongBow test runner has an associated "clipboard" that is specific to a test runner + * and is shared between the runner setup and tear down functions. + * The Test Runner setup may store things on the clipboard, + * the test fixtures and test cases may access them and the test runner tear down destroy them. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @return The LongBowClipBoard for the given LongBowTestRunner. + */ +LongBowClipBoard *longBowTestRunner_GetClipBoard(const LongBowTestRunner *testRunner); + +/** + * Set the configuration for the given LongBowTestRunner. + * + * The LongBowConfig pointed to by configuration is borrowed. + * If it is deallocated, reused, or overwritten results are unpredicable. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + * @param [in] configuration A pointer to a valid LongBowConfig instance. + */ +void longBowTestRunner_SetConfiguration(LongBowTestRunner *testRunner, LongBowConfig *configuration); + +/** + * Get the clipboard data from the given `LongBowTestRunner`. + * + * @param [in] testRunner A pointer to a valid LongBowTestRunner instance. + */ +void *longBowTestRunner_GetClipBoardData(const LongBowTestRunner *testRunner); + +/** + * Update the LongBowConfig instance with information indicated by @p parameter. + * + * @param [in] config A pointer to a valid LongBowConfig instance. + * @param [in] parameter A pointer to nul-terminated C string. + * + * @return true A valid parameter. + * @return false The value of @p parameter is invalid. + */ +bool longBowTestRunner_Config(LongBowConfig *config, const char *parameter); + +/** + * Print command line and configuration help applicable to a Long Bow Test Runner. + * + */ +void longBowTestRunner_ConfigHelp(void); +#endif /* LONGBOWRUNNER_H_ */ -- cgit 1.2.3-korg