atto.h File Reference

Atto - the microscopic C unit test framework. More...

#include <stdio.h>
#include <math.h>
#include <string.h>
#include <stddef.h>

Include dependency graph for atto.h:

Go to the source code of this file.

Macros
#define	ATTO_VERSION   "1.4.0"
	Semantic version of this file and framework.
#define	ATTO_FLOAT_EQ_ABSTOL   (1e-5f)
	Absolute tolerance when comparing two single-precision floating point value for approximate-equality using atto_fapprox(). More...
#define	ATTO_DOUBLE_EQ_ABSTOL   (1e-8)
	Absolute tolerance when comparing two double-precision floating point value for approximate-equality using atto_dapprox(). More...
#define	atto_report()
	Prints a brief report message providing the point where this report is and the amount of successes and failures at this point. More...
#define	atto_assert(expression)
	Verifies if the given boolean expression is true. More...
#define	atto_true(x)   atto_assert(x)
	Verifies if the given boolean expression is true. More...
#define	atto_false(x)   atto_assert(!(x))
	Verifies if the given boolean expression is false. More...
#define	atto_eq(a, b)   atto_assert((a) == (b))
	Verifies if the two arguments are exactly equal. More...
#define	atto_neq(a, b)   atto_assert((a) != (b))
	Verifies if the two arguments are not equal. More...
#define	atto_gt(a, b)   atto_assert((a) > (b))
	Verifies if the first argument is strictly Greater Than the second. More...
#define	atto_ge(a, b)   atto_assert((a) >= (b))
	Verifies if the first argument is Greater or Equal to the second. More...
#define	atto_lt(a, b)   atto_assert((a) < (b))
	Verifies if the first argument is strictly Less Than the second. More...
#define	atto_le(a, b)   atto_assert((a) <= (b))
	Verifies if the first argument is Less or Equal to the second. More...
#define	atto_fdelta(a, b, delta)   atto_assert(fabsf((a) - (b)) <= fabsf(delta))
	Verifies if two single-precision floating point values are within a given absolute tolerance from each other. More...
#define	atto_fapprox(a, b)   atto_fdelta((a), (b), ATTO_FLOAT_EQ_ABSTOL)
	Verifies if two single-precision floating point values are within a fixed absolute tolerance ATTO_FLOAT_EQ_ABSTOL from each other. More...
#define	atto_ddelta(a, b, delta)    atto_assert(fabs((a) - (b)) <= fabs(delta))
	Verifies if two double-precision floating point values are within a given absolute tolerance from each other. More...
#define	atto_dapprox(a, b)   atto_ddelta((a), (b), ATTO_DOUBLE_EQ_ABSTOL)
	Verifies if two double-precision floating point values are within a fixed absolute tolerance ATTO_DOUBLE_EQ_ABSTOL from each other. More...
#define	atto_nan(value)   atto_assert(isnan(value))
	Verifies that the floating point value is Not a Number (NaN). More...
#define	atto_inf(value)   atto_assert(isinf(value))
	Verifies that the floating point value is infinity, either positive or negative. More...
#define	atto_plusinf(value)   atto_assert((isinf(value)) && ((value) > 0))
	Verifies that the floating point value is positive infinity. More...
#define	atto_minusinf(value)   atto_assert((isinf(value)) && ((value) < 0))
	Verifies that the floating point value is negative infinity. More...
#define	atto_finite(value)   atto_assert(isfinite(value))
	Verifies that the floating point value is finite, thus not NaN or +/- infinity. More...
#define	atto_notfinite(value)   atto_assert(!isfinite(value))
	Verifies that the floating point value is not finite, thus either NaN or +/- infinity. More...
#define	atto_flag(value, mask)   atto_assert(((value) & (mask)))
	Verifies if the bits of the value specified by a bit mask are set to 1. More...
#define	atto_noflag(value, mask)   atto_assert(((value) & (mask)) == 0)
	Verifies if the bits of the value specified by a bit mask are set to 0. More...
#define	atto_streq(a, b, maxlen)    atto_assert(strncmp((a), (b), (maxlen)) == 0)
	Verifies if two strings are equal up to a given length or until the shortest string terminates. More...
#define	atto_memeq(a, b, len)   atto_assert(memcmp((a), (b), len) == 0)
	Verifies if two memory sections are equal up to a given length. More...
#define	atto_memneq(a, b, len)   atto_assert(memcmp((a), (b), len) != 0)
	Verifies if two memory sections are different within the given length. More...
#define	atto_zeros(x, len)
	Verifies if a memory section is filled with just zeros. More...
#define	atto_nzeros(x, len)
	Verifies if a memory section is not completely filled with zeros (there is at least one non-zero byte). More...
#define	atto_fail()   atto_assert(0)
	Forces a failure of the test case, stopping it and reporting on standard output.

Variables
char	atto_at_least_one_fail
	Boolean indicating if all tests passed successfully (when 0) or not. More...
size_t	atto_counter_assert_failures
	Counter of all Atto assertion macro calls that failed the check. More...
size_t	atto_counter_assert_passes
	Counter of all Atto assertion macro calls that passed the check. More...

Detailed Description

Atto - the microscopic C unit test framework.

Copyright

Copyright © 2019-2021, Matjaž Guštin dev@m.nosp@m.atja.nosp@m.z.it https://matjaz.it. All rights reserved. License: BSD 3-Clause License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Macro Definition Documentation

ATTO_FLOAT_EQ_ABSTOL

#define ATTO_FLOAT_EQ_ABSTOL   (1e-5f)

Absolute tolerance when comparing two single-precision floating point value for approximate-equality using atto_fapprox().

If the difference between the two float values is bigger than this tolerance, the assertion fails.

ATTO_DOUBLE_EQ_ABSTOL

#define ATTO_DOUBLE_EQ_ABSTOL   (1e-8)

Absolute tolerance when comparing two double-precision floating point value for approximate-equality using atto_dapprox().

If the difference between the two double values is bigger than this tolerance, the assertion fails.

atto_report

#define atto_report

(

)

Value:

    printf("REPORT | File: %s:%d | Test case: %s" \
           " | Passes: %5zu | Failures: %5zu\n", \
           __FILE__, __LINE__, __func__,          \
           atto_counter_assert_passes, atto_counter_assert_failures)

Prints a brief report message providing the point where this report is and the amount of successes and failures at this point.

Particularly useful to call it at the end of the test runner executable or after a certain group of test cases to verify that progress through the test suite is happening. In case of sudden crashes of the test suite, multiple of these reports may be added to aid debugging in understanding where the issue arisees.

atto_assert

#define atto_assert

(

expression

)

Value:

    do {                   \
    if (!(expression)) {                               \
        printf("FAIL | File: %s:%d | Test case: %s\n", \
               __FILE__, __LINE__, __func__);          \
        atto_counter_assert_failures++;                \
        atto_at_least_one_fail = 1;                    \
        return;                                        \
    } else {                                           \
        atto_counter_assert_passes++;                  \
    }                                                  \
} while (0)

Verifies if the given boolean expression is true.

Otherwise stops the test case immediately and reports the failing file, function and line number on standard output.

It's the most generic macro offered by Atto. If you need something more specific, try using the other macros instead.

The do-while(0) construct allows to write multi-line macros.

If your system does not support printf(), replace it with something else in this file! For example a transmit() function to communicate the result to other devices.

Example:

atto_assert(1);      // Passes
atto_assert(0);      // Fails
atto_assert(3 < 1);  // Fails

atto_true

#define atto_true

(

x

)

atto_assert(x)

Verifies if the given boolean expression is true.

Just a rename of atto_assert() for consistency with atto_false().

atto_false

#define atto_false

(

x

)

atto_assert(!(x))

Verifies if the given boolean expression is false.

Otherwise stops the test case immediately and reports the failing file, function and line number on standard output.

Example:

atto_false(1);      // Fails
atto_false(0);      // Passes

atto_eq

#define atto_eq	(		a,
			b
	)		atto_assert((a) == (b))

Verifies if the two arguments are exactly equal.

Otherwise stops the test case immediately and reports the failing file, function and line number on standard output.

It is recommended to use this macro instead of calling atto_assert(a == b) to avoid mistyping the equality comparison operator == into the assignment operator =.

Example:

atto_eq(12, 12);      // Passes
atto_eq(12.0f, 12U);  // Passes due to implicit conversion of 12U to 12.0f
atto_eq(100, 1);      // Fails

atto_neq

#define atto_neq	(		a,
			b
	)		atto_assert((a) != (b))

Verifies if the two arguments are not equal.

Otherwise stops the test case immediately and reports the failing file, function and line number on standard output.

Example:

atto_neq(12, 12);      // Fails
atto_neq(12.0f, 12U);  // Fails
atto_neq(100, 1);      // Passes

atto_gt

#define atto_gt	(		a,
			b
	)		atto_assert((a) > (b))

Verifies if the first argument is strictly Greater Than the second.

Otherwise stops the test case immediately and reports the failing file, function and line number on standard output.

Example:

atto_gt(1, 10);     // Fails
atto_gt(10, 10);    // Fails
atto_gt(100, 10);   // Passes

atto_ge

#define atto_ge	(		a,
			b
	)		atto_assert((a) >= (b))

Verifies if the first argument is Greater or Equal to the second.

Otherwise stops the test case immediately and reports the failing file, function and line number on standard output.

Example:

atto_ge(1, 10);     // Fails
atto_ge(10, 10);    // Passes
atto_ge(100, 10);   // Passes

atto_lt

#define atto_lt	(		a,
			b
	)		atto_assert((a) < (b))

Verifies if the first argument is strictly Less Than the second.

Otherwise stops the test case immediately and reports the failing file, function and line number on standard output.

Example:

atto_lt(1, 10);     // Passes
atto_lt(10, 10);    // Fails
atto_lt(100, 10);   // Fails

atto_le

#define atto_le	(		a,
			b
	)		atto_assert((a) <= (b))

Verifies if the first argument is Less or Equal to the second.

Otherwise stops the test case immediately and reports the failing file, function and line number on standard output.

Example:

atto_le(1, 10);     // Passes
atto_le(10, 10);    // Fails
atto_le(100, 10);   // Fails

atto_fdelta

#define atto_fdelta	(		a,
			b,
			delta
	)		atto_assert(fabsf((a) - (b)) <= fabsf(delta))

Verifies if two single-precision floating point values are within a given absolute tolerance from each other.

Otherwise stops the test case and reports on standard output.

Example:

atto_fdelta(1.0f, 1.00000001f, 0.1f);  // Passes
atto_fdelta(1.0f, 1.1f, 0.15f);        // Passes
atto_fdelta(1.0f, 2.0f, 0.1f);         // Fails

atto_fapprox

#define atto_fapprox	(		a,
			b
	)		atto_fdelta((a), (b), ATTO_FLOAT_EQ_ABSTOL)

Verifies if two single-precision floating point values are within a fixed absolute tolerance ATTO_FLOAT_EQ_ABSTOL from each other.

Useful to check for almost-equality but ignoring minor rounding errors.

Otherwise stops the test case and reports on standard output.

Example:

atto_fapprox(1.0f, 1.000001f);  // Passes
atto_fapprox(1.0f, 1.1);        // Fails

atto_ddelta

#define atto_ddelta	(		a,
			b,
			delta
	)		atto_assert(fabs((a) - (b)) <= fabs(delta))

Verifies if two double-precision floating point values are within a given absolute tolerance from each other.

Otherwise stops the test case and reports on standard output.

Example:

atto_ddelta(1.0, 1.00000001, 0.1);  // Passes
atto_ddelta(1.0, 1.1, 0.15);        // Passes
atto_ddelta(1.0, 2.0, 0.1);         // Fails

atto_dapprox

#define atto_dapprox	(		a,
			b
	)		atto_ddelta((a), (b), ATTO_DOUBLE_EQ_ABSTOL)

Verifies if two double-precision floating point values are within a fixed absolute tolerance ATTO_DOUBLE_EQ_ABSTOL from each other.

Useful to check for almost-equality but ignoring minor rounding errors.

Otherwise stops the test case and reports on standard output.

Example:

atto_dapprox(1.0, 1.00000001);  // Passes
atto_dapprox(1.0, 1.1);         // Fails

atto_nan

#define atto_nan

(

value

)

atto_assert(isnan(value))

Verifies that the floating point value is Not a Number (NaN).

Otherwise stops the test case and reports on standard output.

Example:

atto_nan(NAN);        // Passes
atto_nan(INFINITY);   // Fails
atto_nan(-INFINITY);  // Fails
atto_nan(1.0);        // Fails
atto_nan(1);          // Fails

atto_inf

#define atto_inf

(

value

)

atto_assert(isinf(value))

Verifies that the floating point value is infinity, either positive or negative.

Otherwise stops the test case and reports on standard output.

Example:

atto_inf(NAN);        // Fails
atto_inf(INFINITY);   // Passes
atto_inf(-INFINITY);  // Passes
atto_inf(1.0);        // Fails
atto_inf(1);          // Fails

atto_plusinf

#define atto_plusinf

(

value

)

atto_assert((isinf(value)) && ((value) > 0))

Verifies that the floating point value is positive infinity.

Otherwise stops the test case and reports on standard output.

Example:

atto_plusinf(NAN);        // Fails
atto_plusinf(INFINITY);   // Passes
atto_plusinf(-INFINITY);  // Fails
atto_plusinf(1.0);        // Fails
atto_plusinf(1);          // Fails

atto_minusinf

#define atto_minusinf

(

value

)

atto_assert((isinf(value)) && ((value) < 0))

Verifies that the floating point value is negative infinity.

Otherwise stops the test case and reports on standard output.

Example:

atto_minusinf(NAN);        // Fails
atto_minusinf(INFINITY);   // Fails
atto_minusinf(-INFINITY);  // Passes
atto_minusinf(1.0);        // Fails
atto_minusinf(1);          // Fails

atto_finite

#define atto_finite

(

value

)

atto_assert(isfinite(value))

Verifies that the floating point value is finite, thus not NaN or +/- infinity.

Otherwise stops the test case and reports on standard output.

Example:

atto_finite(NAN);        // Fails
atto_finite(INFINITY);   // Fails
atto_finite(-INFINITY);  // Fails
atto_finite(1.0);        // Passes
atto_finite(1);          // Passes

atto_notfinite

#define atto_notfinite

(

value

)

atto_assert(!isfinite(value))

Verifies that the floating point value is not finite, thus either NaN or +/- infinity.

Otherwise stops the test case and reports on standard output.

Example:

atto_notfinite(NAN);        // Passes
atto_notfinite(INFINITY);   // Passes
atto_notfinite(-INFINITY);  // Passes
atto_notfinite(1.0);        // Fails
atto_notfinite(1);          // Fails

atto_flag

#define atto_flag	(		value,
			mask
	)		atto_assert(((value) & (mask)))

Verifies if the bits of the value specified by a bit mask are set to 1.

Otherwise stops the test case and reports on standard output.

Example:

atto_flag(0x07, 1 << 1);  // Passes
atto_flag(0x07, 0x04);    // Passes
atto_flag(0x07, 0x06);    // Passes
atto_flag(0x07, 0xF0);    // Fails

atto_noflag

#define atto_noflag	(		value,
			mask
	)		atto_assert(((value) & (mask)) == 0)

Verifies if the bits of the value specified by a bit mask are set to 0.

Otherwise stops the test case and reports on standard output.

Example:

atto_noflag(0x07, 1 << 5);  // Passes
atto_noflag(0x07, 0xF8);    // Passes
atto_noflag(0x07, 0x04);    // Fails

atto_streq

#define atto_streq	(		a,
			b,
			maxlen
	)		atto_assert(strncmp((a), (b), (maxlen)) == 0)

Verifies if two strings are equal up to a given length or until the shortest string terminates.

Otherwise stops the test case and reports on standard output.

Example:

atto_streq("abcd", "abcd", 2);    // Passes
atto_streq("abcd", "abcd", 4);    // Passes
atto_streq("abcd", "abcd", 100);  // Passes, reached null terminator
atto_streq("abcd", "ABCD", 4);    // Fails, different casing

atto_memeq

#define atto_memeq	(		a,
			b,
			len
	)		atto_assert(memcmp((a), (b), len) == 0)

Verifies if two memory sections are equal up to a given length.

Otherwise stops the test case and reports on standard output.

Example:

atto_memeq("abcd", "abcd", 2);    // Passes
atto_memeq("abcd", "abcd", 4);    // Passes
atto_memeq("abcd", "abcd", 100);  // UNDEFINED as exceeding known memory
atto_memeq("abcd", "ABCD", 4);    // Fails

atto_memneq

#define atto_memneq	(		a,
			b,
			len
	)		atto_assert(memcmp((a), (b), len) != 0)

Verifies if two memory sections are different within the given length.

Otherwise stops the test case and reports on standard output.

Example:

atto_memneq("abcd", "abcd", 2);    // Fails
atto_memneq("abcd", "abcd", 4);    // Fails
atto_memneq("abcd", "abcd", 100);  // UNDEFINED as exceeding known memory
atto_memneq("abcd", "abCD", 4);    // Passes

atto_zeros

#define atto_zeros	(		x,
			len
	)

Value:

        do { \
        for (size_t __atto_idx = 0; __atto_idx < (size_t)(len); __atto_idx++) \
        { atto_eq(((uint8_t*)(x))[__atto_idx], 0); } \
    } while(0)

Verifies if a memory section is filled with just zeros.

Useful to check whether a memory location has been cleared.

Otherwise stops the test case and reports on standard output.

Example:

atto_zeros("abcd", 2);        // Fails
atto_zeros("\0\0cd", 2);      // Passes
atto_zeros("\0\0cd", 4);      // Fails
atto_zeros("\0\0\0\0", 4);    // Passes
atto_zeros("\0\0\0\0", 100);  // UNDEFINED as exceeding known memory

atto_nzeros

#define atto_nzeros	(		x,
			len
	)

Value:

        do { \
        uint8_t __atto_all_zero = 1; \
        for (size_t __atto_idx = 0; __atto_idx < (size_t)(len); __atto_idx++) \
        { if(((uint8_t*)(x))[__atto_idx] != 0) \
            { __atto_all_zero = 0; break; } \
        } \
        atto_false(__atto_all_zero); \
    } while(0)

Verifies if a memory section is not completely filled with zeros (there is at least one non-zero byte).

Useful to check whether a memory location has been initialised to non-zero values, especially for random strings or data from an outside source we don't know the exact format of.

Otherwise stops the test case and reports on standard output.

Example:

atto_nzeros("abcd", 2);        // Passes
atto_nzeros("\0\0cd", 2);      // Fails
atto_nzeros("\0\0cd", 4);      // Passes
atto_nzeros("\0\0\0\0", 4);    // Fails
atto_nzeros("\0\0c\0", 4);     // Passes
atto_nzeros("a\0c\0", 3);      // Passes
atto_nzeros("\0\0\0\0", 100);  // UNDEFINED as exceeding known memory

Variable Documentation

atto_at_least_one_fail

char atto_at_least_one_fail

extern

Boolean indicating if all tests passed successfully (when 0) or not.

Useful as a value to return from the main function of the test executable, so that the test executable returns non-zero in case at least one test failed.

atto_counter_assert_failures

size_t atto_counter_assert_failures

extern

Counter of all Atto assertion macro calls that failed the check.

The user should not change this value, but may freely read it. Useful to inspect the amount of errors (which should be 0) for changes during different launches of the test suite.

atto_counter_assert_passes

size_t atto_counter_assert_passes

extern

Counter of all Atto assertion macro calls that passed the check.

The user should not change this value, but may freely read it. Useful to inspect the amount of passes for changes during different launches of the test suite.