ztest_test.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_TESTSUITE_ZTEST_TEST_H_
#define ZEPHYR_TESTSUITE_ZTEST_TEST_H_
 
#include <zephyr/app_memory/app_memdomain.h>
#include <zephyr/init.h>
#include <zephyr/sys/iterable_sections.h>
#include <zephyr/sys/util.h>
#include <stdbool.h>
 

 
#if defined(CONFIG_USERSPACE)
#define __USERSPACE_FLAGS (K_USER)
#else
#define __USERSPACE_FLAGS (0)
#endif
 
#ifdef __cplusplus
extern "C" {
#endif

enum ztest_expected_result {
        ZTEST_EXPECTED_RESULT_FAIL = 0, 
        ZTEST_EXPECTED_RESULT_SKIP,     
};

struct ztest_expected_result_entry {
        const char *test_suite_name; 
        const char *test_name;       
        enum ztest_expected_result expected_result; 
};
 
extern struct ztest_expected_result_entry _ztest_expected_result_entry_list_start[];
extern struct ztest_expected_result_entry _ztest_expected_result_entry_list_end[];
 
#define __ZTEST_EXPECT(_suite_name, _test_name, expectation)                                       \
        static const STRUCT_SECTION_ITERABLE(                                                      \
                ztest_expected_result_entry,                                                       \
                UTIL_CAT(UTIL_CAT(z_ztest_expected_result_, _suite_name), _test_name)) = {         \
                        .test_suite_name = STRINGIFY(_suite_name),                                 \
                        .test_name = STRINGIFY(_test_name),                                        \
                        .expected_result = expectation,                                            \
        }

#define ZTEST_EXPECT_FAIL(_suite_name, _test_name)                                                 \
        __ZTEST_EXPECT(_suite_name, _test_name, ZTEST_EXPECTED_RESULT_FAIL)

#define ZTEST_EXPECT_SKIP(_suite_name, _test_name)                                                 \
        __ZTEST_EXPECT(_suite_name, _test_name, ZTEST_EXPECTED_RESULT_SKIP)
 
struct ztest_unit_test {
        const char *test_suite_name;
        const char *name;
        void (*test)(void *data);
        uint32_t thread_options;

        struct ztest_unit_test_stats *const stats;
};

struct ztest_param_values {
        const void *values;
        size_t count;
        size_t elem_size;
        const char *(*name_cb)(size_t index, const void *value);
        void (*value_at_cb)(size_t index, void *out);
        void (*setup_cb)(void);
};

struct ztest_param_inst {
        const char *test_suite_name;
        const char *test_name;
        const char *instance_name;
        const struct ztest_param_values *values;
};
 
extern struct ztest_unit_test _ztest_unit_test_list_start[];
extern struct ztest_unit_test _ztest_unit_test_list_end[];
extern struct ztest_param_inst _ztest_param_inst_list_start[];
extern struct ztest_param_inst _ztest_param_inst_list_end[];
#define ZTEST_TEST_COUNT (_ztest_unit_test_list_end - _ztest_unit_test_list_start)
#define ZTEST_PARAM_INST_COUNT (_ztest_param_inst_list_end - _ztest_param_inst_list_start)

struct ztest_suite_stats {
        uint32_t run_count;
        uint32_t skip_count;
        uint32_t fail_count;
};
 
struct ztest_unit_test_stats {
        uint32_t run_count;
        uint32_t skip_count;
        uint32_t fail_count;
        uint32_t pass_count;
        uint32_t duration_worst_ms;
};

typedef void *(*ztest_suite_setup_t)(void);

typedef void (*ztest_suite_before_t)(void *fixture);

typedef void (*ztest_suite_after_t)(void *fixture);

typedef void (*ztest_suite_teardown_t)(void *fixture);

typedef bool (*ztest_suite_predicate_t)(const void *global_state);

struct ztest_suite_node {
        const char *const name;

        const ztest_suite_setup_t setup;

        const ztest_suite_before_t before;

        const ztest_suite_after_t after;

        const ztest_suite_teardown_t teardown;

        const ztest_suite_predicate_t predicate;

        struct ztest_suite_stats *const stats;
};
 
extern struct ztest_suite_node _ztest_suite_node_list_start[];
extern struct ztest_suite_node _ztest_suite_node_list_end[];

#define ZTEST_SUITE_COUNT (_ztest_suite_node_list_end - _ztest_suite_node_list_start)

#define ZTEST_SUITE(SUITE_NAME, PREDICATE, setup_fn, before_fn, after_fn, teardown_fn)             \
        struct ztest_suite_stats UTIL_CAT(z_ztest_suite_node_stats_, SUITE_NAME);                  \
        static const STRUCT_SECTION_ITERABLE(ztest_suite_node,                                     \
                                             UTIL_CAT(z_ztest_test_node_, SUITE_NAME)) = {         \
                .name = STRINGIFY(SUITE_NAME),                                                     \
                .setup = (setup_fn),                                                               \
                .before = (before_fn),                                                             \
                .after = (after_fn),                                                               \
                .teardown = (teardown_fn),                                                         \
                .predicate = PREDICATE,                                                            \
                .stats = &UTIL_CAT(z_ztest_suite_node_stats_, SUITE_NAME),             \
        }

void ztest_run_all(const void *state, bool shuffle, int suite_iter, int case_iter);

enum ztest_result {
        ZTEST_RESULT_PENDING,
        ZTEST_RESULT_PASS,
        ZTEST_RESULT_FAIL,
        ZTEST_RESULT_SKIP,
        ZTEST_RESULT_SUITE_SKIP,
        ZTEST_RESULT_SUITE_FAIL,
};

enum ztest_phase {
        TEST_PHASE_SETUP,
        TEST_PHASE_BEFORE,
        TEST_PHASE_TEST,
        TEST_PHASE_AFTER,
        TEST_PHASE_TEARDOWN,
        TEST_PHASE_FRAMEWORK,
};

 
#ifdef ZTEST_UNITTEST
int z_impl_ztest_run_test_suites(const void *state, bool shuffle,
                                int suite_iter, int case_iter);
 
static inline int ztest_run_test_suites(const void *state, bool shuffle,
                                int suite_iter, int case_iter)
{
        return z_impl_ztest_run_test_suites(state, shuffle, suite_iter, case_iter);
}
 
#else
__syscall int ztest_run_test_suites(const void *state, bool shuffle,
                                int suite_iter, int case_iter);
#endif
 
#ifdef ZTEST_UNITTEST
void z_impl___ztest_set_test_result(enum ztest_result new_result);
static inline void __ztest_set_test_result(enum ztest_result new_result)
{
        z_impl___ztest_set_test_result(new_result);
}
 
void z_impl___ztest_set_test_phase(enum ztest_phase new_phase);
static inline void __ztest_set_test_phase(enum ztest_phase new_phase)
{
        z_impl___ztest_set_test_phase(new_phase);
}
#else
__syscall void __ztest_set_test_result(enum ztest_result new_result);
__syscall void __ztest_set_test_phase(enum ztest_phase new_phase);
#endif
 

void ztest_verify_all_test_suites_ran(void);

int z_ztest_run_test_suite(const char *name, bool shuffle, int suite_iter,
                        int case_iter, void *param);

struct ztest_unit_test *z_ztest_get_next_test(const char *suite, struct ztest_unit_test *prev);
 
/* definitions for use with testing application shared memory   */
#ifdef CONFIG_USERSPACE
#define ZTEST_DMEM K_APP_DMEM(ztest_mem_partition)
#define ZTEST_BMEM K_APP_BMEM(ztest_mem_partition)
#define ZTEST_SECTION K_APP_DMEM_SECTION(ztest_mem_partition)
extern struct k_mem_partition ztest_mem_partition;
#else
#define ZTEST_DMEM
#define ZTEST_BMEM
#define ZTEST_SECTION .data
#endif

void ztest_test_fail(void);

void ztest_test_pass(void);

void ztest_test_skip(void);
 
 
void ztest_skip_failed_assumption(void);

const void *ztest_get_current_param(void);

size_t ztest_get_current_param_index(void);

size_t ztest_get_current_param_size(void);

bool ztest_has_current_param(void);

#define ZTEST_GET_PARAM_PTR(type) ((const type *)ztest_get_current_param())

#define ZTEST_GET_PARAM(type) (*ZTEST_GET_PARAM_PTR(type))

#define ZTEST_DEFINE_PARAM_VALUES(name_, type_, ...)                                         \
        static const type_ z_ztest_param_arr_##name_[] = {__VA_ARGS__};                     \
        static const struct ztest_param_values name_ = {                                     \
                .values       = z_ztest_param_arr_##name_,                                   \
                .count        = ARRAY_SIZE(z_ztest_param_arr_##name_),                       \
                .elem_size    = sizeof(type_),                                                \
                .name_cb      = NULL,                                                        \
                .value_at_cb  = NULL,                                                        \
                .setup_cb     = NULL,                                                        \
        }

#define ZTEST_DEFINE_PARAM_VALUES_ARRAY(name_, array_)                                       \
        static const struct ztest_param_values name_ = {                                     \
                .values      = (array_),                                                     \
                .count       = ARRAY_SIZE(array_),                                           \
                .elem_size   = sizeof((array_)[0]),                                          \
                .name_cb     = NULL,                                                         \
                .value_at_cb = NULL,                                                         \
                .setup_cb    = NULL,                                                         \
        }

#define ZTEST_DEFINE_PARAM_RANGE(name_, type_, begin_, end_, step_)                          \
        BUILD_ASSERT((end_) > (begin_), "ZTEST_DEFINE_PARAM_RANGE: end must be > begin"); \
        BUILD_ASSERT((step_) > 0, "ZTEST_DEFINE_PARAM_RANGE: step must be > 0");          \
        BUILD_ASSERT(sizeof(type_) <= 16U,                                                   \
                     "ZTEST_DEFINE_PARAM_RANGE: type too large for scratch buffer");        \
        static void z_ztest_range_value_at_##name_(size_t z_idx_, void *z_out_)             \
        {                                                                                    \
                type_ z_val_ = (type_)(begin_) + (type_)(step_) * (type_)(z_idx_);         \
                *(type_ *)z_out_ = z_val_;                                                   \
        }                                                                                    \
        static const struct ztest_param_values name_ = {                                     \
                .values      = NULL,                                                         \
                .count       = (size_t)(((end_) - (begin_) - 1) / (step_) + 1),             \
                .elem_size   = sizeof(type_),                                                \
                .name_cb     = NULL,                                                         \
                .value_at_cb = z_ztest_range_value_at_##name_,                              \
                .setup_cb    = NULL,                                                         \
        }

#define ZTEST_DEFINE_PARAM_GENERATOR(name_, type_, count_, gen_cb_)                          \
        BUILD_ASSERT(sizeof(type_) <= 16U,                                                   \
                     "ZTEST_DEFINE_PARAM_GENERATOR: type too large for scratch buffer");     \
        static const struct ztest_param_values name_ = {                                     \
                .values      = NULL,                                                         \
                .count       = (count_),                                                     \
                .elem_size   = sizeof(type_),                                                \
                .name_cb     = NULL,                                                         \
                .value_at_cb = (gen_cb_),                                                    \
                .setup_cb    = NULL,                                                         \
        }

#define ZTEST_DEFINE_PARAM_GENERATOR_WITH_SETUP(name_, type_, count_, setup_cb_, gen_cb_)    \
        BUILD_ASSERT(sizeof(type_) <= 16U,                                                   \
                     "ZTEST_DEFINE_PARAM_GENERATOR_WITH_SETUP: type too large");             \
        static const struct ztest_param_values name_ = {                                     \
                .values      = NULL,                                                         \
                .count       = (count_),                                                     \
                .elem_size   = sizeof(type_),                                                \
                .name_cb     = NULL,                                                         \
                .value_at_cb = (gen_cb_),                                                    \
                .setup_cb    = (setup_cb_),                                                  \
        }

/* Note: all parameters carry a trailing underscore to avoid name collisions
 * with the struct fields of ztest_param_inst (e.g. a parameter named
 * 'instance_name' would cause the preprocessor to replace the token inside
 * the '.instance_name' designator, producing the invalid '.ints').
 */
#define ZTEST_INSTANTIATE_TEST_SUITE_P(inst_, suite_, fn_, param_values_name_)               \
        static const STRUCT_SECTION_ITERABLE(                                                \
                ztest_param_inst,                                                            \
                UTIL_CAT(UTIL_CAT(z_ztest_param_inst_, suite_),                              \
                         UTIL_CAT(_, UTIL_CAT(fn_, UTIL_CAT(_, inst_))))) = {               \
                .test_suite_name = STRINGIFY(suite_),                                        \
                .test_name       = STRINGIFY(fn_),                                           \
                .instance_name   = STRINGIFY(inst_),                                         \
                .values          = &(param_values_name_),                                    \
        }
 
#define Z_TEST_P(suite, fn, t_options) \
        struct ztest_unit_test_stats z_ztest_unit_test_stats_##suite##_##fn; \
        static void _##suite##_##fn##_wrapper(void *data); \
        /* data carries the suite fixture from setup(); use             */ \
        /* ztest_get_current_param() / ZTEST_GET_PARAM() for the value. */ \
        static void suite##_##fn(void *data); \
        static STRUCT_SECTION_ITERABLE(ztest_unit_test, z_ztest_unit_test__##suite##__##fn) = { \
                .test_suite_name = STRINGIFY(suite), \
                .name = STRINGIFY(fn), \
                .test = (_##suite##_##fn##_wrapper), \
                .thread_options = t_options, \
                .stats = &z_ztest_unit_test_stats_##suite##_##fn \
        }; \
        static void _##suite##_##fn##_wrapper(void *wrapper_data) \
        { \
                 suite##_##fn(wrapper_data); \
        } \
        static inline void suite##_##fn(void *data)
 
 
#define ZTEST_P(suite, fn) Z_TEST_P(suite, fn, 0)

#define ZTEST_USER_P(suite, fn) Z_TEST_P(suite, fn, K_USER)
 
#define Z_TEST(suite, fn, t_options, use_fixture)                                                  \
        struct ztest_unit_test_stats z_ztest_unit_test_stats_##suite##_##fn;                       \
        static void _##suite##_##fn##_wrapper(void *data);                                         \
        static void suite##_##fn(                                                                  \
                COND_CODE_1(use_fixture, (struct suite##_fixture *fixture), (void)));              \
        static STRUCT_SECTION_ITERABLE(ztest_unit_test, z_ztest_unit_test__##suite##__##fn) = {    \
                .test_suite_name = STRINGIFY(suite),                                               \
                .name = STRINGIFY(fn),                                                             \
                .test = (_##suite##_##fn##_wrapper),                                               \
                .thread_options = t_options,                                                       \
                .stats = &z_ztest_unit_test_stats_##suite##_##fn                                   \
        };                                                                                         \
        static void _##suite##_##fn##_wrapper(void *wrapper_data)                                  \
        {                                                                                          \
                COND_CODE_1(use_fixture, (suite##_##fn((struct suite##_fixture *)wrapper_data);),  \
                            (ARG_UNUSED(wrapper_data); suite##_##fn();))                           \
        }                                                                                          \
        static inline void suite##_##fn(                                                           \
                COND_CODE_1(use_fixture, (struct suite##_fixture *fixture), (void)))
 
#define Z_ZTEST(suite, fn, t_options) Z_TEST(suite, fn, t_options, 0)
#define Z_ZTEST_F(suite, fn, t_options) Z_TEST(suite, fn, t_options, 1)

#define Z_TEST_SKIP_IFDEF(config) COND_CODE_1(config, (ztest_test_skip()), ())

#define Z_TEST_SKIP_IFNDEF(config) COND_CODE_1(config, (), (ztest_test_skip()))

#define ZTEST(suite, fn) Z_ZTEST(suite, fn, 0)

#define ZTEST_USER(suite, fn) Z_ZTEST(suite, fn, K_USER)

#define ZTEST_F(suite, fn) Z_ZTEST_F(suite, fn, 0)

#define ZTEST_USER_F(suite, fn) Z_ZTEST_F(suite, fn, K_USER)

typedef void (*ztest_rule_cb)(const struct ztest_unit_test *test, void *data);

struct ztest_test_rule {
        ztest_rule_cb before_each;
        ztest_rule_cb after_each;
};

#define ZTEST_RULE(name, before_each_fn, after_each_fn)                                            \
        static STRUCT_SECTION_ITERABLE(ztest_test_rule, z_ztest_test_rule_##name) = {              \
                .before_each = (before_each_fn),                                                   \
                .after_each = (after_each_fn),                                                     \
        }
 
extern struct ztest_test_rule _ztest_test_rule_list_start[];
extern struct ztest_test_rule _ztest_test_rule_list_end[];

void ztest_simple_1cpu_before(void *data);

void ztest_simple_1cpu_after(void *data);

#define ztest_run_test_suite(suite, shuffle, suite_iter, case_iter, param) \
        z_ztest_run_test_suite(STRINGIFY(suite), shuffle, suite_iter, case_iter, param)

struct ztest_arch_api {
        void (*run_all)(const void *state, bool shuffle, int suite_iter, int case_iter);
        bool (*should_suite_run)(const void *state, struct ztest_suite_node *suite);
        bool (*should_test_run)(const char *suite, const char *test);
};

 
__syscall void z_test_1cpu_start(void);
__syscall void z_test_1cpu_stop(void);
 
__syscall void sys_clock_tick_set(uint64_t tick);
 
#ifdef __cplusplus
}
#endif
 
#ifndef ZTEST_UNITTEST
#include <zephyr/syscalls/ztest_test.h>
#endif
 
#endif /* ZEPHYR_TESTSUITE_ZTEST_TEST_H_ */