utest_harness.h

00001 /****************************************************************************
00002  * Copyright (c) 2015, ARM Limited, All Rights Reserved
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License"); you may
00006  * not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00013  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  ****************************************************************************
00017  */
00018 
00019 #ifndef UTEST_HARNESS_H
00020 #define UTEST_HARNESS_H
00021 
00022 #include <stdint.h>
00023 #include <stdbool.h>
00024 #include <stdio.h>
00025 
00026 #include "utest/utest_types.h"
00027 #include "utest/utest_case.h"
00028 #include "utest/utest_default_handlers.h"
00029 #include "utest/utest_specification.h"
00030 #include "utest/utest_scheduler.h"
00031 
00032 
00033 namespace utest {
00034 /** \addtogroup frameworks */
00035 /** @{*/
00036 namespace v1 {
00037 
00038     /** Test Harness.
00039      *
00040      * This class runs a test specification for you and calls all required handlers.
00041      * The harness executes the test specification in an asynchronous fashion, therefore
00042      * `run()` returns immediately.
00043      *
00044      * @note In case of an test abort, the harness will busy-wait and never finish.
00045      */
00046     class Harness
00047     {
00048     public:
00049         /// Runs a test specification
00050         /// @retval `true`  if the specification can be run
00051         /// @retval `false` if another specification is currently running
00052         static bool run(const Specification& specification);
00053 
00054         /// @cond
00055         __deprecated_message("Start case selection is done by returning the index from the test setup handler!")
00056         static bool run(const Specification& specification, size_t start_case);
00057         /// @endcond
00058 
00059         /// @returns `true` if a test specification is being executed, `false` otherwise
00060         static bool is_busy ();
00061 
00062         /// Sets the scheduler to be used.
00063         /// @return `true` if scheduler is properly specified (all functions non-null).
00064         static bool set_scheduler(utest_v1_scheduler_t scheduler);
00065 
00066         /** Call this function in the asynchronous callback that you have been waiting for.
00067          *
00068          * You can only validate a callback once, calling this function when no callback is expected
00069          * has no side effects.
00070          * After callback validation, the next test case is scheduled.
00071          *
00072          * You may specify additional test case attributes with this callback.
00073          * So for example, you may delay the decision to repeat an asynchronous test case until the callback
00074          * needs to be validated.
00075          *
00076          * However, be aware, that only the repeat attributes can be modified and the usual arbitration rules apply.
00077          * The modified case attributes are only valid until the case handler returns updated attributes.
00078          *
00079          * @param control   the test case attribute to be added to the existing attributes.
00080          */
00081         static void validate_callback(const control_t control = control_t());
00082 
00083         /// Raising a failure causes the failure to be counted and the failure handler to be called.
00084         /// Further action then depends on its return state.
00085         static void raise_failure(const failure_reason_t reason);
00086 
00087     protected:
00088         static void run_next_case();
00089         static void handle_timeout();
00090         static void schedule_next_case();
00091     private:
00092         static void notify_testcases();
00093     };
00094 
00095 }   // namespace v1
00096 }   // namespace utest
00097 
00098 #endif // UTEST_HARNESS_H
00099 
00100 /** @}*/