`reporter.h` File

C++ header file with declarations for the µTest++ test reporter. More...

Included Headers

#include "check-result.h" #include "detail.h" #include "expression-formatter.h" #include "extension.h" #include "reflection.h" #include "runner-options.h" #include <cstdint> #include <cstdio> #include <limits> #include <string_view> #include <string> #include <memory> #include <vector> #include <charconv> #include "inlines/reporter-inlines.h"

Namespaces Index

namespace	micro_os_plus
	The primary namespace for the µOS++ framework. More...

namespace	micro_test_plus
	Primary namespace for the µTest++ testing framework. More...

namespace	detail
	Internal implementation details for the µTest++ framework. More...

Classes Index

struct	indentation
	Parameterised stream manipulator for outputting indentation. More...

struct	open_test_case
	A test case that has begun and not yet ended. More...

struct	output_route
	The destinations of a record. More...

class	reporter
	Abstract base class for the reporters that display test results, including operand values for failures. More...

Enumerations Index

enum class	record_kind : uint8_t { ... }
	The kinds of records written by the reporters. More...

Functions Index

reporter &	endl (reporter &stream)
	Output stream manipulator for ending a line in test reports. More...

indentation	indent (size_t level)
	Factory function that creates an indentation manipulator. More...

Description

C++ header file with declarations for the µTest++ test reporter.

This header provides the declarations for the test reporting facilities used within the µTest++ framework. It defines the endl and indent() stream manipulators, and the abstract reporter base class, which accumulates output in a buffer, writes it to the console and to an optional output file, and dispatches the pass/fail results and the session, suite, and test case events to the concrete reporters (reporter_human and reporter_tap).

The formatting of the values and the comparison expressions is delegated to detail::expression_formatter.

The verbosity levels, and the other session options, are defined in runner-options.h. The manipulators and the reporter are defined in the micro_os_plus::micro_test_plus::detail namespace, since the reporters are internal to the framework.

This file is included by micro-os-plus/micro-test-plus.h, which is the header that the applications include.

Enumerations

record_kind

enum class micro_os_plus::micro_test_plus::detail::record_kind : uint8_t

strong

The kinds of records written by the reporters.

Enumeration values

info	The informational lines written at the beginning of the session
suite_heading	The heading that marks the beginning of a suite
suite_result	The result line of a suite
test_case_heading	The heading that marks the beginning of a test case
test_case_result	The result line of a test case
skipped	The line of a suite or of a test case skipped by the filter
passed_check	The line of a passed check
failed_check	The lines of a failed check, or the failure of a suite
total	The totals of the session
abort	The report of an aborted test execution

The output policy, which decides where each kind of record is written at each verbosity level, is in reporter::route(). The concrete reporters only format the records and ask where they go.

Definition at line 160 of file reporter.h.

161 {

166 info,

167

171 suite_heading,

172

176 suite_result,

177

181 test_case_heading,

182

186 test_case_result,

187

192 skipped,

193

197 passed_check,

198

202 failed_check,

203

207 total,

208

212 abort

213 };

Functions

endl()

reporter & micro_os_plus::micro_test_plus::detail::endl (reporter & stream)

Output stream manipulator for ending a line in test reports.

Calls reporter::end_line(), which appends a line ending to the internal buffer. Unlike std::endl, it does not flush; the buffer is written later, by the concrete reporters.

Parameters

stream

Reference to the reporter instance.

Returns: Reference to the same reporter instance, enabling chaining of output operations.

The endl function calls reporter::end_line(), which appends a newline character to the buffer of the specified reporter.

Definition at line 218 of file reporter.cpp.

218 endl (reporter& stream)

219 {

220 stream.end_line ();

221 return stream;

222 }

References micro_os_plus::micro_test_plus::detail::reporter::end_line and micro_os_plus::micro_test_plus::detail::endl.

indent()

indentation micro_os_plus::micro_test_plus::detail::indent (size_t level)

inline nodiscard

Factory function that creates an indentation manipulator.

Returns an indentation aggregate initialised with level.

Allows writing reporter << indent(n) instead of constructing the manipulator explicitly.

Parameters

level

The number of four-space indentation levels.

Returns: An indentation value for use with operator<<.

Definition at line 64 of file reporter-inlines.h.

64 indent (size_t level)

65 {

66 return { level };

67 }

Reference micro_os_plus::micro_test_plus::detail::indent.

File Listing

The file content with the documentation metadata removed is:

1/*

2 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).

4 *

5 * Permission to use, copy, modify, and/or distribute this software for any

6 * purpose is hereby granted, under the terms of the MIT license.

7 *

8 * If a copy of the license was not distributed with this file, it can be

9 * obtained from https://opensource.org/licenses/mit.

10 */

12// ----------------------------------------------------------------------------

39#ifndef MICRO_OS_PLUS_MICRO_TEST_PLUS_REPORTER_H_

40#define MICRO_OS_PLUS_MICRO_TEST_PLUS_REPORTER_H_

42// ----------------------------------------------------------------------------

44#if defined(__cplusplus)

46// ----------------------------------------------------------------------------

48#if __has_include("micro-os-plus/project-config.h")

49#include "micro-os-plus/project-config.h"

50#endif // __has_include("micro-os-plus/project-config.h")

52#if __has_include("micro-os-plus/micro-test-plus-defines.h")

53#include "micro-os-plus/micro-test-plus-defines.h"

54#endif // __has_include("micro-os-plus/micro-test-plus-defines.h")

56#include "check-result.h"

57#include "detail.h"

58#include "expression-formatter.h"

59#include "extension.h"

60#include "reflection.h"

61#include "runner-options.h"

63#include <cstdint>

64#include <cstdio>

65#include <limits>

66#include <string_view>

67#include <string>

68#include <memory>

69#include <vector>

70#include <charconv>

72// ----------------------------------------------------------------------------

74#if defined(__GNUC__)

75#pragma GCC diagnostic push

77#pragma GCC diagnostic ignored "-Wpadded"

78#pragma GCC diagnostic ignored "-Waggregate-return"

79#if defined(__clang__)

80#pragma clang diagnostic ignored "-Wc++98-compat"

81#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"

82#endif // defined(__clang__)

83#endif // defined(__GNUC__)

85// ============================================================================

87namespace micro_os_plus::micro_test_plus

88{

89 // --------------------------------------------------------------------------

91 // Forward definitions.

92 class runner;

93 class suite;

94 class test_case;

96 namespace detail

97 {

98 class check_result;

99 class reporter;

100 class stopwatch;

101

114 reporter&

115 endl (reporter& stream);

116

117 // ------------------------------------------------------------------------

118

126 struct indentation

127 {

134 size_t level;

135 };

136

147 [[nodiscard]] indentation

148 indent (size_t level);

149

150 // ========================================================================

151

160 enum class record_kind : uint8_t

161 {

166 info,

167

171 suite_heading,

172

176 suite_result,

177

181 test_case_heading,

182

186 test_case_result,

187

192 skipped,

193

197 passed_check,

198

202 failed_check,

203

207 total,

208

212 abort

213 };

214

221 struct output_route

222 {

229 bool console;

230

238 bool file;

239 };

240

241 // ========================================================================

242

275 class reporter

276 {

284 friend class micro_test_plus::test_case;

285

293 friend class check_result;

294

301 friend class micro_test_plus::runner;

302

303 public:

310 explicit reporter (const runner_options& opts);

311

319 virtual ~reporter ();

320

327 reporter&

328 operator<<(std::string_view sv);

329

336 reporter&

337 operator<<(char c);

338

350 reporter&

351 operator<<(const char* s);

352

359 reporter&

360 operator<<(bool v);

361

367 reporter& operator<<(std::nullptr_t);

368

377 template <class T>

378 requires std::is_arithmetic_v<T>

379 reporter&

380 operator<<(T v);

381

395 template <typename T>

396 requires (not std::is_same_v<T, char>)

397 reporter&

398 operator<< (T* v);

399

406 reporter&

407 operator<<(reporter& (*func) (reporter&));

408

418 reporter&

419 operator<<(indentation m);

420

421 // ----------------------------------------------------------------------

422

436 void

437 end_line (void);

438

451 void

452 flush_streams (void);

453

468 [[nodiscard]] bool

469 has_output_file_error (void) const noexcept;

470

471#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

476

490 [[deprecated ("use runner::verbosity_level() (since 6.0.0)"),

491 nodiscard]] auto

492 verbosity (void) const noexcept -> micro_test_plus::verbosity;

493

497#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

498

499 // ----------------------------------------------------------------------

500

510 void

511 pass (const std::string& message, const std::string& expression,

512 const test_case& test_case);

513

530 virtual void

531 pass_without_text (const test_case& test_case)

532 = 0;

533

545 void

546 fail (const failure_info& failure, const std::string& expression,

547 const test_case& test_case);

548

549 // ----------------------------------------------------------------------

550

562 virtual void

563 begin_session (const runner& runner)

564 = 0;

565

577 virtual void

578 end_session (const runner& runner)

579 = 0;

580

593 virtual void

594 begin_suite (const suite& suite)

595 = 0;

596

611 virtual void

612 end_suite (const suite& suite)

613 = 0;

614

630 virtual void

631 skip_suite (const suite& suite)

632 = 0;

633

655 virtual void

656 fail_suite (const std::string& message, const suite& suite)

657 = 0;

658

672 virtual void

673 begin_test_case (const test_case& test_case)

674 = 0;

675

687 virtual void

688 end_test_case (const test_case& test_case)

689 = 0;

690

707 virtual void

708 skip_test_case (const test_case& test_case)

709 = 0;

710

741 virtual void

742 abort_session (const reflection::source_location& location,

743 bool is_requirement)

744 = 0;

745

757 virtual const char*

758 comment_prefix (void) const noexcept

759 = 0;

760

774 virtual const char*

775 error_prefix (void) const noexcept;

776

795 [[nodiscard]] bool

796 writes_passed_checks (void) const noexcept;

797

798 // ----------------------------------------------------------------------

799

800 protected:

815 void

816 write_buffer_to_file (void);

817

846 [[nodiscard]] output_route

847 route (record_kind kind) const noexcept;

848

865 [[nodiscard]] std::string_view

866 console_lines (bool failed) const noexcept;

867

880 void

881 write_console_text (std::string_view text);

882

896 void

897 mark_failure (size_t begin);

898

912 void

913 enter_suite (const suite& suite, bool displayed);

914

930 void

931 write_console (const char* format, ...)

932#if defined(__GNUC__)

933 __attribute__ ((format (printf, 2, 3)))

934#endif // defined(__GNUC__)

935 ;

936

949 void

950 write_file (const char* format, ...)

951#if defined(__GNUC__)

952 __attribute__ ((format (printf, 2, 3)))

953#endif // defined(__GNUC__)

954 ;

955

976 void

977 write_line (bool to_console, const char* format, ...)

978#if defined(__GNUC__)

979 __attribute__ ((format (printf, 3, 4)))

980#endif // defined(__GNUC__)

981 ;

982

993 void

994 write_info (const std::vector<std::string>& arguments);

995

1013 void

1014 announce_output_file (void);

1015

1028 void

1029 clear_buffer (void);

1030

1040 static constexpr size_t elapsed_time_size_ = 40;

1041

1060 static void

1061 format_elapsed_time (const stopwatch& stopwatch,

1062 char (&message)[elapsed_time_size_]);

1063

1082 static constexpr size_t totals_size_

1083 = 94 + 6 * (std::numeric_limits<size_t>::digits10 + 1);

1084

1103 static void

1104 format_session_totals (const runner& runner,

1105 char (&message)[totals_size_]);

1106

1124 static void

1125 format_suite_totals (const suite& suite, char (&message)[totals_size_]);

1126

1145 static void

1146 format_test_case_totals (const test_case& test_case,

1147 char (&message)[totals_size_]);

1148

1162 virtual void

1163 commit_buffer (void)

1164 = 0;

1165

1180 void

1181 commit_outer_results (void);

1182

1195 virtual void

1196 output_pass_prefix (const std::string& message,

1197 const test_case& test_case)

1198 = 0;

1199

1210 virtual void

1211 output_pass_suffix (const test_case& test_case)

1212 = 0;

1213

1229 virtual void

1230 output_fail_prefix (const std::string& message,

1231 const bool has_expression,

1232 const reflection::source_location& location,

1233 const test_case& test_case)

1234 = 0;

1235

1250 virtual void

1251 output_fail_suffix (const reflection::source_location& location,

1252 check_kind kind, const test_case& test_case)

1253 = 0;

1254

1255 protected:

1263 static constexpr size_t indent_size_ = 4;

1264

1273 const micro_test_plus::verbosity verbosity_;

1274

1284 colours colours_{};

1285

1294 std::string buffer_{};

1295

1305 bool buffer_has_failures_{ false };

1306

1316 std::string failures_{};

1317

1324 struct open_test_case

1325 {

1332 const test_case* test;

1333

1342 bool name_displayed;

1343 };

1344

1352 std::vector<open_test_case> open_test_cases_{};

1353

1371 void

1372 display_open_test_cases (bool include_last);

1373

1389 virtual void

1390 display_open_heading (const open_test_case& open, bool is_first)

1391 = 0;

1392

1399 const suite* current_suite_{ nullptr };

1400

1410 bool suite_displayed_{ false };

1411

1423 expression_formatter expression_{ colours_ };

1424

1434 bool add_empty_line_{ true };

1435

1444 bool has_output_file_error_{ false };

1445

1454 std::string output_file_path_{};

1455

1465 FILE* output_file_{ nullptr };

1466 };

1467

1468 // ------------------------------------------------------------------------

1469 } // namespace detail

1470} // namespace micro_os_plus::micro_test_plus

1471

1472#if defined(__GNUC__)

1473#pragma GCC diagnostic pop

1474#endif // defined(__GNUC__)

1475

1476// ----------------------------------------------------------------------------

1477

1478#endif // defined(__cplusplus)

1479

1480// ============================================================================

1481// Templates, inlines & constexpr implementations.

1482

1483#include "inlines/reporter-inlines.h"

1484

1485// ----------------------------------------------------------------------------

1486

1487#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_REPORTER_H_

1488

1489// ----------------------------------------------------------------------------

Generated via doxygen2docusaurus 2.2.8 by Doxygen 1.18.0.

Included Headers​

Namespaces Index​

Classes Index​

Enumerations Index​

Functions Index​

Description​

Enumerations​

record_kind​

Functions​

endl()​

indent()​

File Listing​