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 namespace v1 {
00035 
00036     /** Test Harness.
00037      *
00038      * This class runs a test specification for you and calls all required handlers.
00039      * The harness executes the test specification in an asynchronous fashion, therefore
00040      * `run()` returns immediately.
00041      *
00042      * By default, this harness uses the MINAR scheduler for asynchronous callbacks.
00043      * If you wamt to provide your own custom scheduler, set `config.utest.use_custom_scheduler` to `true`
00044      * inside your yotta config and set a custom scheduler implementation using the `set_scheduler()` function.
00045      * You must set the scheduler before running a specification.
00046      *
00047      * @note In case of an test abort, the harness will busy-wait and never finish.
00048      */
00049     class Harness
00050     {
00051     public:
00052         /// Runs a test specification
00053         /// @retval `true`  if the specification can be run
00054         /// @retval `false` if another specification is currently running
00055         static bool run(const Specification& specification);
00056 
00057         /// @cond
00058         __deprecated_message("Start case selection is done by returning the index from the test setup handler!")
00059         static bool run(const Specification& specification, size_t start_case);
00060         /// @endcond
00061 
00062         /// @returns `true` if a test specification is being executed, `false` otherwise
00063         static bool is_busy ();
00064 
00065         /// Sets the scheduler to be used.
00066         /// @return `true` if scheduler is properly specified (all functions non-null).
00067         static bool set_scheduler(utest_v1_scheduler_t scheduler);
00068 
00069         /** Call this function in the asynchronous callback that you have been waiting for.
00070          *
00071          * You can only validate a callback once, calling this function when no callback is expected
00072          * has no side effects.
00073          * After callback validation, the next test case is scheduled.
00074          *
00075          * You may specify additional test case attributes with this callback.
00076          * So for example, you may delay the decision to repeat an asynchronous test case until the callback
00077          * needs to be validated.
00078          *
00079          * However, be aware, that only the repeat attributes can be modified and the usual arbitration rules apply.
00080          * The modified case attributes are only valid until the case handler returns updated attributes.
00081          *
00082          * @param control   the test case attribute to be added to the existing attributes.
00083          */
00084         static void validate_callback(const control_t control = control_t());
00085 
00086         /// Raising a failure causes the failure to be counted and the failure handler to be called.
00087         /// Further action then depends on its return state.
00088         static void raise_failure(const failure_reason_t reason);
00089 
00090     protected:
00091         static void run_next_case();
00092         static void handle_timeout();
00093         static void schedule_next_case();
00094     private:
00095         static void notify_testcases();
00096     };
00097 
00098 }   // namespace v1
00099 }   // namespace utest
00100 
00101 #endif // UTEST_HARNESS_H