Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix #963, improve documentation of UtAssert API calls #974

Merged
merged 1 commit into from
May 11, 2021
Merged

Fix #963, improve documentation of UtAssert API calls #974

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 140 additions & 33 deletions ut_assert/inc/utassert.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,61 +83,98 @@ typedef struct
* Macro Definitions
*/

/* A simplified UtAssert that uses the expression itself as the description */
/**
* \brief A simplified UtAssert that uses the expression itself as the description
*/
#define UtAssert_Simple(Expression) UtAssert(Expression, #Expression, __FILE__, __LINE__)

/* Evaluates a expression as either true or false. true means the test passed, false means the test failed. */
/**
* \brief Evaluates a expression as either true or false.
*
* true means the test passed, false means the test failed.
*/
#define UtAssert_True(Expression, ...) UtAssertEx(Expression, UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Evaluates a expression as either true or false. true means the test passed, false means the test failed. */
/**
* \copydoc UtAssert_True
*/
#define UtAssert_Bool(Expression, ...) UtAssertEx(Expression, UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Asserts a test failure */
/**
* \brief Asserts a test failure
*/
#define UtAssert_Failed(...) UtAssertEx(false, UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Assert a test Not Applicable */
/**
* \brief Assert a test Not Applicable
*/
#define UtAssert_NA(...) UtAssertEx(false, UTASSERT_CASETYPE_NA, __FILE__, __LINE__, __VA_ARGS__)

/* Compares two integers and determines if they are equal within a specified absolute tolerance. */
/**
* \brief Compares two integers and determines if they are equal within a specified absolute tolerance.
*/
#define UtAssert_IntegerCmpAbs(x, y, Tolerance, ...) \
UtAssertEx((abs((x) - (y)) <= (Tolerance)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Compares two floating point numbers and determines if they are equal within a specified absolute tolerance. */
/**
* \brief Compares two floating point numbers and determines if they are equal within a specified absolute tolerance.
*/
#define UtAssert_DoubleCmpAbs(x, y, Tolerance, ...) \
UtAssertEx((fabs((x) - (y)) <= (Tolerance)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Compares two floating point numbers and determines if they are equal within a specified relative tolerance. */
/**
* \brief Compares two floating point numbers and determines if they are equal within a specified relative tolerance.
*/
#define UtAssert_DoubleCmpRel(x, y, Ratio, ...) \
UtAssertEx((fabs((x) - (y)) / (x) <= (Ratio)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Compares two strings and determines if they are equal. */
/**
* \brief Compares two strings and determines if they are equal.
*/
#define UtAssert_StrCmp(String1, String2, ...) \
UtAssertEx((strcmp(String1, String2) == 0), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Compares at most Length characters of two strings and determines if they are equal. */
/**
* \brief Compares at most Length characters of two strings and determines if they are equal.
*/
#define UtAssert_StrnCmp(String1, String2, Length, ...) \
UtAssertEx((strncmp(String1, String2, Length) == 0), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Compares two regions of memory and determines if they are equal. */
/**
* \brief Compares two regions of memory and determines if they are equal.
*/
#define UtAssert_MemCmp(Memory1, Memory2, Length, ...) \
UtAssertEx((memcmp(Memory1, Memory2, Length) == 0), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Compares a region of memory to a static pattern and determines if they are equal. Note: Use UtMemSet to
* fill a region of memory with a static pattern. */
/**
* \brief Compares a region of memory to a static pattern and determines if they are equal.
*
* \note Use standard memset() to fill a region of memory with a static pattern.
*/
#define UtAssert_MemCmpValue(Memory, Value, Length, ...) \
UtAssertEx((UtMemCmpValue(Memory, Value, Length)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Compares a region of memory to a byte count pattern and determines if they are equal. Note: Use UtMemFill to
* fill a region of memory with a byte count pattern. */
/**
* \brief Compares a region of memory to a byte count pattern and determines if they are equal.
*
* \note Use UtMemFill() to fill a region of memory with a byte count pattern.
* \sa UtMemFill
*/
#define UtAssert_MemCmpCount(Memory, Length, ...) \
UtAssertEx((UtMemCmpCount(Memory, Length)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* Compares a region of memory with the contents of a binary file and determines if they are equal. Note: Use
* UtMem2BinFile to copy a region of memory to a binary file. */
/**
* \brief Compares a region of memory with the contents of a binary file and determines if they are equal.
*
* \note Use UtMem2BinFile() to copy a region of memory to a binary file.
* \sa UtMem2BinFile
*/
#define UtAssert_Mem2BinFileCmp(Memory, Filename, ...) \
UtAssertEx((UtMem2BinFileCmp(Memory, Filename)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__)

/* A wrapper around UtAssertEx that allows the user to specify the failure type and a more descriptive message */
/**
* \brief A wrapper around UtAssertEx that allows the user to specify the failure type and a more descriptive message
*/
#define UtAssert_Type(Type, Expression, ...) \
UtAssertEx(Expression, UTASSERT_CASETYPE_##Type, __FILE__, __LINE__, __VA_ARGS__)

Expand Down Expand Up @@ -233,43 +270,113 @@ typedef struct
* Exported Functions
*/

/* Returns the number of asserts that have passed. */
/**
* \brief Returns the number of asserts that have passed.
*
* \returns Number of tests that have passed
*/
uint32 UtAssert_GetPassCount(void);

/* Returns the number of asserts that have failed. */
/**
* \brief Returns the number of asserts that have failed.
*
* \returns Number of tests that have failed
*/
uint32 UtAssert_GetFailCount(void);

/* Returns the full status of UtAssert counters */
/**
* \brief Returns the full status of UtAssert counters
*
* \returns Pointer to structure with all the current test counter values
*/
const UtAssert_TestCounter_t *UtAssert_GetCounters(void);

/* Begins a test Segment */
/**
* \brief Begins a test Segment
*
* \param SegmentName the name of the test segment, for logging/output classification
*/
void UtAssert_BeginTest(const char *SegmentName);

/* Completes a test Segment */
/**
* \brief Completes a test Segment
*
* Segment name and counters will be printed to the console
*/
void UtAssert_EndTest(void);

/* Sets the context of the current test, which is the default message type for UtAssert calls */
/**
* \brief Sets the context of the current test, which is the default message type for UtAssert calls
*
* General assert statements for which do not directly specify a case type will inherit this case type
* if an assert fails. The framework automatically sets this to #UTASSERT_CASETYPE_TSF during setup
* and #UTASSERT_CASETYPE_TTF during teardown.
*
* \sa UtAssert_GetContext
*
* \param Context the case type to use for general assert failures
*/
void UtAssert_SetContext(UtAssert_CaseType_t Context);

/* Sets the context of the current test, which is the default message type for UtAssert calls */
/**
* \brief Sets the context of the current test, which is the default message type for UtAssert calls
*
* \sa UtAssert_SetContext
*
* \returns Case type that was set previously via UtAssert_SetContext
*/
UtAssert_CaseType_t UtAssert_GetContext(void);

/* Sets the context of the current test, which is the default message type for UtAssert calls */
/**
* \brief Gets the segment name of the current test
*
* This is the name that was previously set via UtAssert_BeginTest()
*
* \note the appliction should not store this pointer, it may become
* invalid after the next call to UtAssert_EndTest()
*
* \returns pointer to current segment name
*/
const char *UtAssert_GetSegmentName(void);

/* Base assert function. All asserts must call this function. */
/**
* \brief Base assert function
*
* This basic function is provided for backward compatibility with older
* versions of Ut Assert. It generates an assert case using the current
* default context.
*
* Users should preferentially use one of the more type-specific assert macros,
* if available.
*
* \param Expression a boolean value which evaluates "true" if the test passes
* \param Description a free form string describing the test case
* \param File The source file name in which the test case appears
* \param Line The source line number in which the test case appears
*/
bool UtAssert(bool Expression, const char *Description, const char *File, uint32 Line);

/*
* Assert function with CaseType (supports MIR, TSF, NA in addition to FAIL).
* Also supports printf-style message strings to allow more dynamic content in the messages
/**
* \brief Assert function with specific CaseType (supports MIR, TSF, NA in addition to FAIL).
*
* This assert routine allows more consise description of the test case, as it supports
* printf-style message strings to allow dynamic content in the messages.
*
* \param Expression a boolean value which evaluates "true" if the test passes
* \param CaseType the case type to report if expression is "false" (TSF, TTF, FAIL, DEBUG, etc)
* \param File The source file name in which the test case appears
* \param Line The source line number in which the test case appears
* \param MessageFormat a free form printf-style format string describing the test case
*/
bool UtAssertEx(bool Expression, UtAssert_CaseType_t CaseType, const char *File, uint32 Line, const char *MessageFormat,
...) OS_PRINTF(5, 6);

/*
* Aborts the entire test
* (for failures which going on is meaningless or impossible)
/**
* \brief Aborts the entire test
*
* This may be used for fundamental failures, after which going on becomes meaningless or impossible.
*
* \param Message a free form string describing the failure
*/
void UtAssert_Abort(const char *Message);

Expand Down
102 changes: 88 additions & 14 deletions ut_assert/inc/uttools.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,36 +38,110 @@
* Exported Functions
*/

/* Copies a region of memory to a binary file. This file can be reloaded by calling UtBinFile2Mem or it can be
* used to verify test results by calling UtMem2BinFileCmp. */
/**
* \brief Copies a region of memory to a binary file.
*
* This file can be reloaded by calling UtBinFile2Mem or it can be
* used to verify test results by calling UtMem2BinFileCmp.
*
* \sa UtBinFile2Mem, UtMem2BinFileCmp
*
* \param Memory pointer to memory region
* \param Filename file name to use
* \param Length size of memory region
*
* \returns true if copy was successful
*/
bool UtMem2BinFile(const void *Memory, const char *Filename, uint32 Length);

/* Copies a binary file to a region of memory. */
/**
* \brief Copies a binary file to a region of memory.
*
* \param Memory pointer to memory region
* \param Filename file name to use
* \param Length size of memory region
*
* \returns true if copy was successful
*/
bool UtBinFile2Mem(void *Memory, const char *Filename, uint32 Length);

/* Copies a region of memory to a hex file */
/**
* \brief Copies a region of memory to a hex file
*
* \param Memory pointer to memory region
* \param Filename file name to use
* \param Length size of memory region
*
* \returns true if copy was successful
*/
bool UtMem2HexFile(const void *Memory, const char *Filename, uint32 Length);

/* Fills a region of memory with a byte count pattern. */
/**
* \brief Fills a region of memory with a byte count pattern.
*
* \param Memory pointer to memory region
* \param Length size of memory region
*/
void UtMemFill(void *Memory, uint32 Length);

/* Just like the standard sprintf except it returns a pointer to the result string. The result string
* cannot be larger than 256 bytes. */
/**
* \brief Just like the standard sprintf except it returns a pointer to the result string.
*
* The result string cannot be larger than 256 bytes, and will be truncated if the output
* would exceed that length
*
* \param Spec Printf-style format string
*
* \returns pointer to result string
*/
char *UtSprintf(const char *Spec, ...);

/* Calls UtPrintf to print a range of memory as hex bytes. */
/**
* \brief print a range of memory as hex bytes.
*
* \param Memory pointer to memory region
* \param Length size of memory region
*/
void UtPrintx(const void *Memory, uint32 Length);

/* Compares a region of memory to a static pattern and determines if they are equal. Note: Use UtMemSet to
* fill a region of memory with a static pattern. */
/**
* \brief Compares a region of memory to a static pattern and determines if they are equal.
*
* \note Use standard memset() to fill a region of memory with a static value.
*
* \param Memory pointer to memory region
* \param Value static fill value to check for
* \param Length size of memory region
*
* \returns true if check was successful
*/
bool UtMemCmpValue(const void *Memory, uint8 Value, uint32 Length);

/* Compares a region of memory to a byte count pattern and determines if they are equal. Note: Use UtMemFill to
* fill a region of memory with a byte count pattern. */
/**
* \brief Compares a region of memory to a byte count pattern and determines if they are equal.
*
* \note Use UtMemFill() to fill a region of memory with a byte count pattern.
*
* \param Memory pointer to memory region
* \param Length size of memory region
*
* \returns true if check was successful
*/
bool UtMemCmpCount(const void *Memory, uint32 Length);

/* Compares a region of memory with the contents of a binary file and determines if they are equal. Note: Use
* UtMem2BinFile to copy a region of memory to a binary file. */
/**
* \brief Compares a region of memory with the contents of a binary file and determines if they are equal.
*
* \note Use UtMem2BinFile to copy a region of memory to a binary file.
*
* The size of the file determines the size of the memory region to check. The memory region must be
* at least the size of the file.
*
* \param Memory pointer to memory region
* \param Filename file name to use
*
* \returns true if check was successful
*/
bool UtMem2BinFileCmp(const void *Memory, const char *Filename);

/* Macros to implement simple printf-like functions for unit testing */
Expand Down