[#BloombergLP-bsls-AssertTest]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bsls.adoc[bsls]::AssertTest
:relfileprefix: ../../
:mrdocs:

This utility `struct` provides a suite of methods designed for use in conjunction with preprocessor macros during the negative testing of defensive checks using the facilities provided by the `bsls_assert` component. Unlike usual BDE functionality methods in this `struct` provide wide contracts because they need to function without assertion failures during testing, under unforeseen circumstances.

== Synopsis

Declared in `<bsls_asserttest.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
struct AssertTest;
----

== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsls/AssertTest/catchProbe.adoc[`catchProbe`] 
| Return `true` if the specified `expectedResult` is `F` (for Fail), the specified `checkLevel` flag is `false` or the `expectedLevel` is as wide or wider than the actual assertion failure level, the specified `caughtException` contains valid fields, and the specified `testDriverFileName` is either null or refers to the same (valid) component name as the filename in `caughtException`; otherwise, return `false`. If `expectedResult`, `testDriverFileName`, or any field of `caughtException` is invalid (i.e., an invalid filename, null or empty expression text, or a non‐positive line number), this function reports the invalid value(s) to `stdout` before returning `false`. If `testDriverFileName` is not null, but does not reflect the same component name as the otherwise valid filename in `caughtException`, this function prints a message delineating the mismatching deduced component names to `stdout` before returning `false`.
| xref:BloombergLP/bsls/AssertTest/catchProbeRaw.adoc[`catchProbeRaw`] 
| Return `true` if the specified `expectedResult` is `F` (for Fail), the specified `checkLevel` flag is `false` or the `expectedLevel` is as wide or wider than the actual assertion failure level, and the specified `caughtException` contains valid fields; otherwise, return `false`. If `expectedResult`, `expectedLevel`, or any field of `caughtException` is invalid (i.e., an invalid filename, null or empty expression text, or a non‐positive line number), this function reports the invalid value(s) to `stdout` before returning `false`.
| xref:BloombergLP/bsls/AssertTest/failTestDriver.adoc[`failTestDriver`]  [.small]#[noreturn]#
| Throw an `AssertTestException` having the pointer values `text` and `file` and the integer `line` from the specified `violation` as its salient attributes, provided that `BDE_BUILD_TARGET_EXC` is defined; otherwise, log an appropriate message and abort the program (similar to `Assert::failAbort`). Note that this function is intended to have a signature compatible with a registered assertion‐failure handler function in `bsls_assert`.
| xref:BloombergLP/bsls/AssertTest/failTestDriverByReview.adoc[`failTestDriverByReview`] 
| Throw an `AssertTestException` having the `comment`, `fileName`, and `lineNumber` taken from the specified `violation` as its salient attributes, provided that `BDE_BUILD_TARGET_EXC` is defined; otherwise, log an appropriate message and abort the program (similar to `Assert::failAbort`). Note that this function is intended to have a signature compatible with a registered assertion‐failure handler function in `bsls_assert`.
| xref:BloombergLP/bsls/AssertTest/isValidAssertBuild.adoc[`isValidAssertBuild`] 
| Return `true` if the specified `specString` represents a valid textual description of an assertion build type, and `false` otherwise. `specString` is valid if it refers to a null‐terminated character string of length either 1 or 2, where the first character is an (UPPERCASE) `S`, `A`, `O`, or `I`, and the second character, if present, is the numeral `2`. Note that `S`, `A`, `O`, and `I` are intended to represent the respective assertion types `BSLS_ASSERT_SAFE`, `BSLS_ASSERT`, `BSLS_ASSERT_OPT`, and `BSLS_ASSERT_INVOKE`, and the optional `2` is intended to indicate that the component (and program as a whole) was built with `BDE_BUILD_TARGET_SAFE_2` defined. The behavior is undefined unless `specString` points to a null terminated string (C string).
| xref:BloombergLP/bsls/AssertTest/isValidExpected.adoc[`isValidExpected`] 
| Return `true` if the specified `specChar` represents a valid description of the expected result, and `false` otherwise. `specChar` is valid if it is either an (UPPERCASE) `P` (for Pass) or `F` (for Fail). Note that `P` is intended to represent the expectation that the function under test will "pass" by satisfying all preconditions, including the specific one guarded by the assertion under test, while an `F` is intended to indicate the expectation that the specific assertion under test will "fail" (thereby triggering a call to the currently‐installed assertion‐failure handler).
| xref:BloombergLP/bsls/AssertTest/isValidExpectedLevel.adoc[`isValidExpectedLevel`] 
| Return `true` if the specified `specChar` represents a valid description of the expected assert level, and `false` otherwise. `specChar` is valid if it is either a `O` (for `OPT`), `S` (for `SAFE`), `A` (for `ASSERT`), or `I` (for `INVOKE`).
| xref:BloombergLP/bsls/AssertTest/tryProbe.adoc[`tryProbe`] 
| Return `true` if the specified `expectedResult` is `P` (for Pass) and the specified `expectedLevel` is a valid level; otherwise, return `false`. If `expectedResult` is anything other than `P` or `F` (for Fail), this function reports the invalid `expectedResult` value to `stdout` before returning `false`. If `expectedlevel` is anything other than `S`, `A`, `O`, or `I`, this function reports the invalid `expectedLevel` value to `stdout` before returning `false`.
| xref:BloombergLP/bsls/AssertTest/tryProbeRaw.adoc[`tryProbeRaw`] 
| Return `true` if the specified `expectedResult` is `P` (for Pass) and the specified `expectedLevel` is a valid level; otherwise, return `false`. If `expectedResult` is anything other than `P` or `F` (for Fail), this function reports the invalid `expectedResult` value to `stdout` before returning `false`. If `expectedlevel` is anything other than `S`, `A`, `O`, or `I`, this function reports the invalid `expectedLevel` value to `stdout` before returning `false`.
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#