Crashpad

Classes | Functions
crashpad::test Namespace Reference

The testing namespace, for use in test code only. More...

## Classes
class | ChildLauncher
| Creates a child process for testing. Uses gtest `ASSERT_*` to indicate failure. The child's output is passed through a pipe and is available via stdout_read_handle(), and the child's input is attached to a second pipe available via stdin_write_handle(). More...
class | MachMultiprocess
| Manages a Mach-aware multiprocess test. More...
struct | MinidumpWritableTraits
| A traits class defining whether a minidump object type is required to appear only as a fixed-size object or if it is variable-sized. More...
class | Multiprocess
| Manages a multiprocess test. More...
class | MultiprocessExec
| Manages an `exec()`-based multiprocess test. More...
class | Paths
| Functions to obtain paths from within tests. More...
class | ScopedTempDir
| A RAII object that creates a temporary directory for testing. More...
class | TestExceptionSnapshot
| A test ExceptionSnapshot that can carry arbitrary data for testing purposes. More...
class | TestMemoryMapRegionSnapshot
| A test MemoryMapRegionSnapshot that can carry arbitrary data for testing purposes. More...
class | TestMemorySnapshot
| A test MemorySnapshot that can carry arbitrary data for testing purposes. More...
class | TestMinidumpMemoryWriter
| A SnapshotMinidumpMemoryWriter implementation used for testing. More...
class | TestModuleSnapshot
| A test ModuleSnapshot that can carry arbitrary data for testing purposes. More...
class | TestProcessSnapshot
| A test ProcessSnapshot that can carry arbitrary data for testing purposes. More...
class | TestSystemSnapshot
| A test SystemSnapshot that can carry arbitrary data for testing purposes. More...
class | TestThreadSnapshot
| A test ThreadSnapshot that can carry arbitrary data for testing purposes. More...
class | TestUInt32MinidumpWritable
| An internal::MinidumpWritable that carries a `uint32_t` for testing. More...
class | WinChildProcess
| Facilitates the launching of child processes from unit tests. More...
class | WinMultiprocess
| Manages a multiprocess test on Windows. More...

## Functions
const MINIDUMP_HEADER * | MinidumpHeaderAtStart (const std::string &file_contents, const MINIDUMP_DIRECTORY **directory)
| Returns the MINIDUMP_HEADER at the start of a minidump file, along with the MINIDUMP_DIRECTORY it references. More...
void | VerifyMinidumpHeader (const MINIDUMP_HEADER *header, uint32_t streams, uint32_t timestamp)
| Verifies, via gtest assertions, that a MINIDUMP_HEADER contains expected values. More...
void | ExpectMinidumpMemoryDescriptor (const MINIDUMP_MEMORY_DESCRIPTOR *expected, const MINIDUMP_MEMORY_DESCRIPTOR *observed)
| Verifies, via gtest assertions, that a MINIDUMP_MEMORY_DESCRIPTOR structure contains expected values. More...
void | ExpectMinidumpMemoryDescriptorAndContents (const MINIDUMP_MEMORY_DESCRIPTOR *expected, const MINIDUMP_MEMORY_DESCRIPTOR *observed, const std::string &file_contents, uint8_t value, bool at_eof)
| Verifies, via gtest assertions, that a MINIDUMP_MEMORY_DESCRIPTOR structure contains expected values, and that the memory region it points to contains expected values assuming it was written by a TestMinidumpMemoryWriter object. More...
const MinidumpRVAList * | MinidumpRVAListAtStart (const std::string &file_contents, size_t count)
| Returns the MinidumpRVAList at the start of a minidump file. More...
const MINIDUMP_STRING * | MinidumpStringAtRVA (const std::string &file_contents, RVA rva)
| Returns a MINIDUMP_STRING located within a minidump file’s contents. More...
const MinidumpUTF8String * | MinidumpUTF8StringAtRVA (const std::string &file_contents, RVA rva)
| Returns a MinidumpUTF8String located within a minidump file’s contents. More...
base::string16 | MinidumpStringAtRVAAsString (const std::string &file_contents, RVA rva)
| Returns the contents of a MINIDUMP_STRING as a `string16`. More...
std::string | MinidumpUTF8StringAtRVAAsString (const std::string &file_contents, RVA rva)
| Returns the contents of a MinidumpUTF8String as a `std::string`. More...
const void * | MinidumpWritableAtLocationDescriptorInternal (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location, size_t expected_size, bool allow_oversized_data)
| Returns an untyped minidump object located within a minidump file’s contents, where the offset and size of the object are known. More...
template<>
const IMAGE_DEBUG_MISC * | MinidumpWritableAtLocationDescriptor< IMAGE_DEBUG_MISC > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const MINIDUMP_HEADER * | MinidumpWritableAtLocationDescriptor< MINIDUMP_HEADER > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const MINIDUMP_MEMORY_LIST * | MinidumpWritableAtLocationDescriptor< MINIDUMP_MEMORY_LIST > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const MINIDUMP_MODULE_LIST * | MinidumpWritableAtLocationDescriptor< MINIDUMP_MODULE_LIST > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const MINIDUMP_UNLOADED_MODULE_LIST * | MinidumpWritableAtLocationDescriptor< MINIDUMP_UNLOADED_MODULE_LIST > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const MINIDUMP_THREAD_LIST * | MinidumpWritableAtLocationDescriptor< MINIDUMP_THREAD_LIST > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const MINIDUMP_HANDLE_DATA_STREAM * | MinidumpWritableAtLocationDescriptor< MINIDUMP_HANDLE_DATA_STREAM > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const MINIDUMP_MEMORY_INFO_LIST * | MinidumpWritableAtLocationDescriptor< MINIDUMP_MEMORY_INFO_LIST > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const MinidumpModuleCrashpadInfoList * | MinidumpWritableAtLocationDescriptor< MinidumpModuleCrashpadInfoList > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const MinidumpSimpleStringDictionary * | MinidumpWritableAtLocationDescriptor< MinidumpSimpleStringDictionary > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const CodeViewRecordPDB20 * | MinidumpWritableAtLocationDescriptor< CodeViewRecordPDB20 > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
template<>
const CodeViewRecordPDB70 * | MinidumpWritableAtLocationDescriptor< CodeViewRecordPDB70 > (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MINIDUMP_DIRECTORY)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MINIDUMP_MEMORY_LIST)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MINIDUMP_MODULE_LIST)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MINIDUMP_UNLOADED_MODULE_LIST)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MINIDUMP_THREAD_LIST)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MINIDUMP_HANDLE_DATA_STREAM)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MINIDUMP_MEMORY_INFO_LIST)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MinidumpModuleCrashpadInfoList)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MinidumpRVAList)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MinidumpSimpleStringDictionary)
| MINIDUMP_ALLOW_OVERSIZED_DATA (IMAGE_DEBUG_MISC)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MINIDUMP_STRING)
| MINIDUMP_ALLOW_OVERSIZED_DATA (CodeViewRecordPDB20)
| MINIDUMP_ALLOW_OVERSIZED_DATA (CodeViewRecordPDB70)
| MINIDUMP_ALLOW_OVERSIZED_DATA (MinidumpUTF8String)
| MINIDUMP_ALLOW_OVERSIZED_DATA (uint8_t)
template<typename T >
const T * | TMinidumpWritableAtLocationDescriptor (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
| Returns a typed minidump object located within a minidump file’s contents, where the offset and size of the object are known. More...
template<typename T >
const T * | MinidumpWritableAtLocationDescriptor (const std::string &file_contents, const MINIDUMP_LOCATION_DESCRIPTOR &location)
| Returns a typed minidump object located within a minidump file’s contents, where the offset and size of the object are known. More...
template<typename T >
const T * | MinidumpWritableAtRVA (const std::string &file_contents, RVA rva)
| Returns a typed minidump object located within a minidump file’s contents, where the offset of the object is known. More...
std::string | ErrnoMessage (int err, const std::string &base=std::string())
| Formats an error message using an `errno` value. More...
std::string | ErrnoMessage (const std::string &base=std::string())
| Formats an error message using `errno`. More...
std::string | ErrorMessage (const std::string &base=std::string())
| Formats an error message using `GetLastError()`. More...
bool | FileExists (const base::FilePath &path)
| Determines whether a file exists. More...
FileOffset | FileSize (const base::FilePath &path)
| Determines the size of a file. More...
std::string | BytesToHexString (const void *bytes, size_t length)
| Returns a hexadecimal string corresponding to bytes and length. More...
std::string | MachErrorMessage (mach_error_t mach_err, const std::string &base=std::string())
| Formats a Mach error message. More...
std::string | BootstrapErrorMessage (kern_return_t bootstrap_err, const std::string &base=std::string())
| Formats a bootstrap error message. More...
std::string | ReadStreamToString (HTTPBodyStream *stream)
| Reads a HTTPBodyStream to a string. If an error occurs, adds a test failure and returns an empty string. More...
std::string | ReadStreamToString (HTTPBodyStream *stream, size_t buffer_size)
| Reads a HTTPBodyStream to a string. If an error occurs, adds a test failure and returns an empty string. More...
void | InitializeMinidumpContextX86 (MinidumpContextX86 *context, uint32_t seed)
| Initializes a context structure for testing. More...
void | InitializeMinidumpContextAMD64 (MinidumpContextAMD64 *context, uint32_t seed)
| Initializes a context structure for testing. More...
void | ExpectMinidumpContextX86 (uint32_t expect_seed, const MinidumpContextX86 *observed, bool snapshot)
| Verifies, via gtest assertions, that a context structure contains expected values. More...
void | ExpectMinidumpContextAMD64 (uint32_t expect_seed, const MinidumpContextAMD64 *observed, bool snapshot)
| Verifies, via gtest assertions, that a context structure contains expected values. More...
void | InitializeCPUContextX86 (CPUContext *context, uint32_t seed)
| Initializes a context structure for testing. More...
void | InitializeCPUContextX86_64 (CPUContext *context, uint32_t seed)
| Initializes a context structure for testing. More...
void | InitializeCPUContextX86Fxsave (CPUContextX86::Fxsave *fxsave, uint32_t *seed)
| Initializes an `fxsave` context substructure for testing. More...
void | InitializeCPUContextX86_64Fxsave (CPUContextX86_64::Fxsave *fxsave, uint32_t *seed)
| Initializes an `fxsave` context substructure for testing. More...

## Detailed Description

The testing namespace, for use in test code only.

## Function Documentation

## ◆ BootstrapErrorMessage()

std::string crashpad::test::BootstrapErrorMessage | ( | kern_return_t | bootstrap_err,
|  | const std::string & | base = `std::string()`
| ) |  |

Formats a bootstrap error message.

The returned string will combine the base string, if supplied, with a a textual and numeric description of the error.

Parameters

  [in] | bootstrap_err | The bootstrap error code.
  [in] | base | A string to prepend to the error description.

Returns
  A string of the format `"Permission denied (1100)"` if bootstrap_err has the value `BOOTSTRAP_NOT_PRIVILEGED` on a system where this is defined to be 1100. If base is not empty, it will be prepended to this string, separated by a colon. If bootstrap_err is not a valid bootstrap error code, it will be interpreted as a Mach error code in the manner of MachErrorMessage().

## ◆ BytesToHexString()

std::string crashpad::test::BytesToHexString | ( | const void * | bytes,
|  | size_t | length
| ) |  |

Returns a hexadecimal string corresponding to bytes and length.

Example usage:

uint8_t expected[10];
uint8_t observed[10];
// …
EXPECT_EQ(BytesToHexString(expected, arraysize(expected)),
BytesToHexString(observed, arraysize(observed)));

## ◆ ErrnoMessage() [1/2]

std::string crashpad::test::ErrnoMessage | ( | int | err,
|  | const std::string & | base = `std::string()`
| ) |  |

Formats an error message using an `errno` value.

The returned string will combine the base string, if supplied, with a a textual and numeric description of the error.

The message is formatted using `strerror()`. err may be `0` or outside of the range of known error codes, and the message returned will contain the string that `strerror()` uses in these cases.

Parameters

  [in] | err | The error code, usable as an `errno` value.
  [in] | base | A string to prepend to the error description.

Returns
  A string of the format `"Operation not permitted (1)"` if err has the value `EPERM` on a system where this is defined to be `1`. If base is not empty, it will be prepended to this string, separated by a colon.

## ◆ ErrnoMessage() [2/2]

std::string crashpad::test::ErrnoMessage | ( | const std::string & | base = `std::string()` | ) |

Formats an error message using `errno`.

The returned string will combine the base string, if supplied, with a a textual and numeric description of the error.

The message is formatted using `strerror()`. `errno` may be `0` or outside of the range of known error codes, and the message returned will contain the string that `strerror()` uses in these cases.

Parameters

  [in] | base | A string to prepend to the error description.

Returns
  A string of the format `"Operation not permitted (1)"` if `errno` has the value `EPERM` on a system where this is defined to be `1`. If base is not empty, it will be prepended to this string, separated by a colon.

## ◆ ErrorMessage()

std::string crashpad::test::ErrorMessage | ( | const std::string & | base = `std::string()` | ) |

Formats an error message using `GetLastError()`.

The returned string will combine the base string, if supplied, with a a textual and numeric description of the error. The format is the same as the `PLOG()` formatting in base.

## ◆ ExpectMinidumpContextAMD64()

void crashpad::test::ExpectMinidumpContextAMD64 | ( | uint32_t | expect_seed,
|  | const MinidumpContextAMD64 * | observed,
|  | bool | snapshot
| ) |  |

Verifies, via gtest assertions, that a context structure contains expected values.

Parameters

  [in] | expect_seed | The seed value used to initialize a context structure. This is the seed value used with InitializeMinidumpContext*().
  [in] | observed | The context structure to check. All fields of this structure will be compared against the expected context structure, one initialized with expect_seed.
  [in] | snapshot | If `true`, compare observed to a context structure expected to be produced from a CPUContext snapshot. If `false`, compare observed to a native minidump context structure. CPUContext snapshot structures may carry different sets of data than native minidump context structures in meaningless ways. When `true`, fields not found in CPUContext structures are expected to be `0`. When `false`, all fields are compared. This makes it possible to test both that these fields are passed through correctly by the native minidump writer and are zeroed out when creating a minidump context structure from a CPUContext structure.

## ◆ ExpectMinidumpContextX86()

void crashpad::test::ExpectMinidumpContextX86 | ( | uint32_t | expect_seed,
|  | const MinidumpContextX86 * | observed,
|  | bool | snapshot
| ) |  |

Verifies, via gtest assertions, that a context structure contains expected values.

Parameters

  [in] | expect_seed | The seed value used to initialize a context structure. This is the seed value used with InitializeMinidumpContext*().
  [in] | observed | The context structure to check. All fields of this structure will be compared against the expected context structure, one initialized with expect_seed.
  [in] | snapshot | If `true`, compare observed to a context structure expected to be produced from a CPUContext snapshot. If `false`, compare observed to a native minidump context structure. CPUContext snapshot structures may carry different sets of data than native minidump context structures in meaningless ways. When `true`, fields not found in CPUContext structures are expected to be `0`. When `false`, all fields are compared. This makes it possible to test both that these fields are passed through correctly by the native minidump writer and are zeroed out when creating a minidump context structure from a CPUContext structure.

## ◆ ExpectMinidumpMemoryDescriptor()

void crashpad::test::ExpectMinidumpMemoryDescriptor | ( | const MINIDUMP_MEMORY_DESCRIPTOR * | expected,
|  | const MINIDUMP_MEMORY_DESCRIPTOR * | observed
| ) |  |

Verifies, via gtest assertions, that a MINIDUMP_MEMORY_DESCRIPTOR structure contains expected values.

In expected and observed, MINIDUMP_MEMORY_DESCRIPTOR::StartOfMemoryRange and MINIDUMP_LOCATION_DESCRIPTOR::DataSize are compared and must match. If MINIDUMP_LOCATION_DESCRIPTOR::Rva is nonzero in expected, the same field in observed must match it, subject to a 16-byte alignment augmentation.

Parameters

  [in] | expected | A MINIDUMP_MEMORY_DESCRIPTOR structure containing expected values.
  [in] | observed | A MINIDUMP_MEMORY_DESCRIPTOR structure containing observed values.

## ◆ ExpectMinidumpMemoryDescriptorAndContents()

void crashpad::test::ExpectMinidumpMemoryDescriptorAndContents | ( | const MINIDUMP_MEMORY_DESCRIPTOR * | expected,
|  | const MINIDUMP_MEMORY_DESCRIPTOR * | observed,
|  | const std::string & | file_contents,
|  | uint8_t | value,
|  | bool | at_eof
| ) |  |

Verifies, via gtest assertions, that a MINIDUMP_MEMORY_DESCRIPTOR structure contains expected values, and that the memory region it points to contains expected values assuming it was written by a TestMinidumpMemoryWriter object.

expected and observed are compared by ExpectMinidumpMemoryDescriptor().

Parameters

  [in] | expected | A MINIDUMP_MEMORY_DESCRIPTOR structure containing expected values.
  [in] | observed | A MINIDUMP_MEMORY_DESCRIPTOR structure containing observed values.
  [in] | file_contents | The contents of the minidump file in which observed was found. The memory region referenced by observed will be read from this string.
  [in] | value | The value used to create a TestMinidumpMemoryWriter. Each byte of memory in the region referenced by observed must be this value.
  [in] | at_eof | If `true`, the region referenced by observed must appear at the end of file_contents, without any data following it.

## ◆ FileExists()

bool crashpad::test::FileExists | ( | const base::FilePath & | path | ) |

Determines whether a file exists.

Parameters

  [in] | path | The path to check for existence.

Returns
  `true` if path exists. `false` if it does not exist. If an error other than “file not found” occurs when searching for path, returns `false` with a gtest failure added.

## ◆ FileSize()

FileOffset crashpad::test::FileSize | ( | const base::FilePath & | path | ) |

Determines the size of a file.

Parameters

  [in] | path | The path of the file to check. The file must exist.

Returns
  The size of the file at path. If the file does not exist, or an error occurs when attempting to determine its size, returns `-1` with a gtest failure added.

## ◆ InitializeCPUContextX86()

void crashpad::test::InitializeCPUContextX86 | ( | CPUContext * | context,
|  | uint32_t | seed
| ) |  |

Initializes a context structure for testing.

Initialization is compatible with the initialization used by minidump context test initialization functions such as InitializeMinidumpContextX86() and InitializeMinidumpContextAMD64() for identical seed values.

Parameters

  [out] | context | The structure to initialize.
  [in] | seed | The seed value. Initializing two context structures of the same type with identical seed values should produce identical context structures. Initialization with a different seed value should produce a different context structure. If seed is `0`, context is zeroed out entirely except for the CPUContext::architecture field, which will identify the context type. If seed is nonzero, context will be populated entirely with nonzero values.

## ◆ InitializeCPUContextX86_64()

void crashpad::test::InitializeCPUContextX86_64 | ( | CPUContext * | context,
|  | uint32_t | seed
| ) |  |

Initializes a context structure for testing.

Initialization is compatible with the initialization used by minidump context test initialization functions such as InitializeMinidumpContextX86() and InitializeMinidumpContextAMD64() for identical seed values.

Parameters

  [out] | context | The structure to initialize.
  [in] | seed | The seed value. Initializing two context structures of the same type with identical seed values should produce identical context structures. Initialization with a different seed value should produce a different context structure. If seed is `0`, context is zeroed out entirely except for the CPUContext::architecture field, which will identify the context type. If seed is nonzero, context will be populated entirely with nonzero values.

## ◆ InitializeCPUContextX86_64Fxsave()

void crashpad::test::InitializeCPUContextX86_64Fxsave | ( | CPUContextX86_64::Fxsave * | fxsave,
|  | uint32_t * | seed
| ) |  |

Initializes an `fxsave` context substructure for testing.

Parameters

  [out] | fxsave | The structure to initialize.
  [in,out] | seed | The seed value. Initializing two `fxsave` structures of the same type with identical seed values should produce identical structures. Initialization with a different seed value should produce a different `fxsave` structure. If seed is `0`, fxsave is zeroed out entirely. If seed is nonzero, fxsave will be populated entirely with nonzero values. seed will be updated by this function to allow the caller to perform subsequent initialization of the context structure containing fxsave.

## ◆ InitializeCPUContextX86Fxsave()

void crashpad::test::InitializeCPUContextX86Fxsave | ( | CPUContextX86::Fxsave * | fxsave,
|  | uint32_t * | seed
| ) |  |

Initializes an `fxsave` context substructure for testing.

Parameters

  [out] | fxsave | The structure to initialize.
  [in,out] | seed | The seed value. Initializing two `fxsave` structures of the same type with identical seed values should produce identical structures. Initialization with a different seed value should produce a different `fxsave` structure. If seed is `0`, fxsave is zeroed out entirely. If seed is nonzero, fxsave will be populated entirely with nonzero values. seed will be updated by this function to allow the caller to perform subsequent initialization of the context structure containing fxsave.

## ◆ InitializeMinidumpContextAMD64()

void crashpad::test::InitializeMinidumpContextAMD64 | ( | MinidumpContextAMD64 * | context,
|  | uint32_t | seed
| ) |  |

Initializes a context structure for testing.

Initialization is compatible with the initialization used by CPUContext test initialization functions such as InitializeCPUContextX86() and InitializeCPUContextX86_64() for identical seed values.

Parameters

  [out] | context | The structure to initialize.
  [in] | seed | The seed value. Initializing two context structures of the same type with identical seed values should produce identical context structures. Initialization with a different seed value should produce a different context structure. If seed is `0`, context is zeroed out entirely except for the flags field, which will identify the context type. If seed is nonzero, context will be populated entirely with nonzero values.

## ◆ InitializeMinidumpContextX86()

void crashpad::test::InitializeMinidumpContextX86 | ( | MinidumpContextX86 * | context,
|  | uint32_t | seed
| ) |  |

Initializes a context structure for testing.

Initialization is compatible with the initialization used by CPUContext test initialization functions such as InitializeCPUContextX86() and InitializeCPUContextX86_64() for identical seed values.

Parameters

  [out] | context | The structure to initialize.
  [in] | seed | The seed value. Initializing two context structures of the same type with identical seed values should produce identical context structures. Initialization with a different seed value should produce a different context structure. If seed is `0`, context is zeroed out entirely except for the flags field, which will identify the context type. If seed is nonzero, context will be populated entirely with nonzero values.

## ◆ MachErrorMessage()

std::string crashpad::test::MachErrorMessage | ( | mach_error_t | mach_err,
|  | const std::string & | base = `std::string()`
| ) |  |

Formats a Mach error message.

The returned string will combine the base string, if supplied, with a a textual and numeric description of the error.

Parameters

  [in] | mach_err | The Mach error code, which may be a `kern_return_t` or related type.
  [in] | base | A string to prepend to the error description.

Returns
  A string of the format `"(os/kern) invalid address (1)"` if mach_err has the value `KERN_INVALID_ADDRESS` on a system where this is defined to be 1. If base is not empty, it will be prepended to this string, separated by a colon.

## ◆ MinidumpHeaderAtStart()

const MINIDUMP_HEADER * crashpad::test::MinidumpHeaderAtStart | ( | const std::string & | file_contents,
|  | const MINIDUMP_DIRECTORY ** | directory
| ) |  |

Returns the MINIDUMP_HEADER at the start of a minidump file, along with the MINIDUMP_DIRECTORY it references.

This function validates the MINIDUMP_HEADER::Signature and MINIDUMP_HEADER::Version fields.

Parameters

  [in] | file_contents | The contents of the minidump file.
  [out] | directory | The MINIDUMP_DIRECTORY referenced by the MINIDUMP_HEADER. If the MINIDUMP_HEADER does not reference a MINIDUMP_DIRECTORY, `nullptr` without raising a gtest assertion. If the referenced MINIDUMP_DIRECTORY is not valid, `nullptr` with a gtest assertion raised. On failure, `nullptr`.

Returns
  On success, the MINIDUMP_HEADER at the beginning of the minidump file. On failure, raises a gtest assertion and returns `nullptr`.

## ◆ MinidumpRVAListAtStart()

const MinidumpRVAList * crashpad::test::MinidumpRVAListAtStart | ( | const std::string & | file_contents,
|  | size_t | count
| ) |  |

Returns the MinidumpRVAList at the start of a minidump file.

Parameters

  [in] | file_contents | The contents of the minidump file.
  [in] | count | The number of RVA objects expected in the MinidumpRVAList. This function will only be successful if exactly this many objects are present, and if space for them exists in file_contents.

Returns
  On success, the MinidumpRVAList at the beginning of the file. On failure, raises a gtest assertion and returns `nullptr`.

## ◆ MinidumpStringAtRVA()

const MINIDUMP_STRING * crashpad::test::MinidumpStringAtRVA | ( | const std::string & | file_contents,
|  | RVA | rva
| ) |  |

Returns a MINIDUMP_STRING located within a minidump file’s contents.

If rva points outside of the range of file_contents, if the string has an incorrect length or is not `NUL`-terminated, or if any of the string data would lie outside of the range of file_contents, this function will fail.

Parameters

  [in] | file_contents | The contents of the minidump file.
  [in] | rva | The offset within the minidump file of the desired MINIDUMP_STRING.

Returns
  On success, a pointer to the MINIDUMP_STRING in file_contents. On failure, raises a gtest assertion and returns `nullptr`.

See also
  MinidumpStringAtRVAAsString()
  MinidumpUTF8StringAtRVA()

## ◆ MinidumpStringAtRVAAsString()

base::string16 crashpad::test::MinidumpStringAtRVAAsString | ( | const std::string & | file_contents,
|  | RVA | rva
| ) |  |

Returns the contents of a MINIDUMP_STRING as a `string16`.

This function uses MinidumpStringAtRVA() to obtain a MINIDUMP_STRING, and returns the string data as a `string16`.

Parameters

  [in] | file_contents | The contents of the minidump file.
  [in] | rva | The offset within the minidump file of the desired MINIDUMP_STRING.

Returns
  On success, the string read from file_writer at offset rva. On failure, raises a gtest assertion and returns an empty string.

See also
  MinidumpUTF8StringAtRVAAsString()

## ◆ MinidumpUTF8StringAtRVA()

const MinidumpUTF8String * crashpad::test::MinidumpUTF8StringAtRVA | ( | const std::string & | file_contents,
|  | RVA | rva
| ) |  |

Returns a MinidumpUTF8String located within a minidump file’s contents.

If rva points outside of the range of file_contents, if the string has an incorrect length or is not `NUL`-terminated, or if any of the string data would lie outside of the range of file_contents, this function will fail.

Parameters

  [in] | file_contents | The contents of the minidump file.
  [in] | rva | The offset within the minidump file of the desired MinidumpUTF8String.

Returns
  On success, a pointer to the MinidumpUTF8String in file_contents. On failure, raises a gtest assertion and returns `nullptr`.

See also
  MinidumpUTF8StringAtRVAAsString()
  MinidumpStringAtRVA()

## ◆ MinidumpUTF8StringAtRVAAsString()

std::string crashpad::test::MinidumpUTF8StringAtRVAAsString | ( | const std::string & | file_contents,
|  | RVA | rva
| ) |  |

Returns the contents of a MinidumpUTF8String as a `std::string`.

This function uses MinidumpUTF8StringAtRVA() to obtain a MinidumpUTF8String, and returns the string data as a `std::string`.

Parameters

  [in] | file_contents | The contents of the minidump file.
  [in] | rva | The offset within the minidump file of the desired MinidumpUTF8String.

Returns
  On success, the string read from file_writer at offset rva. On failure, raises a gtest assertion and returns an empty string.

See also
  MinidumpStringAtRVAAsString()

## ◆ MinidumpWritableAtLocationDescriptor()

template<typename T >

const T* crashpad::test::MinidumpWritableAtLocationDescriptor | ( | const std::string & | file_contents,
|  | const MINIDUMP_LOCATION_DESCRIPTOR & | location
| ) |  |

Returns a typed minidump object located within a minidump file’s contents, where the offset and size of the object are known.

This function has template specializations that perform more stringent checking than the default implementation:

- With a MINIDUMP_HEADER template parameter, a template specialization ensures that the structure’s magic number and version fields are correct.
- With a MINIDUMP_MEMORY_LIST, MINIDUMP_THREAD_LIST, MINIDUMP_MODULE_LIST, MINIDUMP_MEMORY_INFO_LIST, or MinidumpSimpleStringDictionary template parameter, template specializations ensure that the size given by location matches the size expected of a stream containing the number of elements it claims to have.
- With an IMAGE_DEBUG_MISC, CodeViewRecordPDB20, or CodeViewRecordPDB70 template parameter, template specializations ensure that the structure has the expected format including any magic number and the `NUL`- terminated string.

Parameters

  [in] | file_contents | The contents of the minidump file.
  [in] | location | A MINIDUMP_LOCATION_DESCRIPTOR giving the offset within the minidump file of the desired object, as well as its size.

Returns
  If the size of location is at least as big as the size of the requested object, and if location is within the range of file_contents, returns a pointer into file_contents at offset rva. Otherwise, raises a gtest assertion failure and returns `nullptr`.

See also
  MinidumpWritableAtRVA()

## ◆ MinidumpWritableAtLocationDescriptorInternal()

const void * crashpad::test::MinidumpWritableAtLocationDescriptorInternal | ( | const std::string & | file_contents,
|  | const MINIDUMP_LOCATION_DESCRIPTOR & | location,
|  | size_t | expected_size,
|  | bool | allow_oversized_data
| ) |  |

Returns an untyped minidump object located within a minidump file’s contents, where the offset and size of the object are known.

Parameters

  [in] | file_contents | The contents of the minidump file.
  [in] | location | A MINIDUMP_LOCATION_DESCRIPTOR giving the offset within the minidump file of the desired object, as well as its size.
  [in] | expected_size | The expected size of the object. If allow_oversized_data is `true`, expected_size is treated as the minimum size of location, but it is permitted to be larger. If allow_oversized_data is `false`, the size of location must match expected_size exactly.
  [in] | allow_oversized_data | Controls whether expected_size is a minimum limit (`true`) or an exact match is required (`false`).

Returns
  If the size of location is agrees with expected_size, and if location is within the range of file_contents, returns a pointer into file_contents at offset rva. Otherwise, raises a gtest assertion failure and returns `nullptr`.

Do not call this function. Use the typed version, MinidumpWritableAtLocationDescriptor<>(), or another type-specific function.

## ◆ MinidumpWritableAtRVA()

template<typename T >

const T* crashpad::test::MinidumpWritableAtRVA | ( | const std::string & | file_contents,
|  | RVA | rva
| ) |  |

Returns a typed minidump object located within a minidump file’s contents, where the offset of the object is known.

Parameters

  [in] | file_contents | The contents of the minidump file.
  [in] | rva | The offset within the minidump file of the desired object.

Returns
  If rva plus the size of an object of type T is within the range of file_contents, returns a pointer into file_contents at offset rva. Otherwise, raises a gtest assertion failure and returns `nullptr`.

See also
  MinidumpWritableAtLocationDescriptor<>()

## ◆ ReadStreamToString() [1/2]

std::string crashpad::test::ReadStreamToString | ( | HTTPBodyStream * | stream | ) |

Reads a HTTPBodyStream to a string. If an error occurs, adds a test failure and returns an empty string.

Parameters

  [in] | stream | The stream from which to read.

Returns
  The contents of the stream, or an empty string on failure.

## ◆ ReadStreamToString() [2/2]

std::string crashpad::test::ReadStreamToString | ( | HTTPBodyStream * | stream,
|  | size_t | buffer_size
| ) |  |

Reads a HTTPBodyStream to a string. If an error occurs, adds a test failure and returns an empty string.

Parameters

  [in] | stream | The stream from which to read.
  [in] | buffer_size | The size of the buffer to use when reading from the stream.

Returns
  The contents of the stream, or an empty string on failure.

## ◆ TMinidumpWritableAtLocationDescriptor()

template<typename T >

const T* crashpad::test::TMinidumpWritableAtLocationDescriptor | ( | const std::string & | file_contents,
|  | const MINIDUMP_LOCATION_DESCRIPTOR & | location
| ) |  |

Returns a typed minidump object located within a minidump file’s contents, where the offset and size of the object are known.

This function is similar to MinidumpWritableAtLocationDescriptor<>() and is used to implement that function. It exists independently so that template specializations are able to call this function, which provides the default implementation.

Do not call this function directly. Use MinidumpWritableAtLocationDescriptor<>() instead.

## ◆ VerifyMinidumpHeader()

void crashpad::test::VerifyMinidumpHeader | ( | const MINIDUMP_HEADER * | header,
|  | uint32_t | streams,
|  | uint32_t | timestamp
| ) |  |

Verifies, via gtest assertions, that a MINIDUMP_HEADER contains expected values.

All fields in the MINIDUMP_HEADER will be evaluated except for the Signature and Version fields, because those are checked by MinidumpHeaderAtStart(). Most other fields are are compared to their correct default values. MINIDUMP_HEADER::NumberOfStreams is compared to streams, and MINIDUMP_HEADER::TimeDateStamp is compared to timestamp. Most fields are checked with nonfatal EXPECT-style assertions, but MINIDUMP_HEADER::NumberOfStreams and MINIDUMP_HEADER::StreamDirectoryRva are checked with fatal ASSERT-style assertions, because they must be correct in order for processing of the minidump to continue.