tts::output_sink Struct Reference

Customization point for where TTS output actually goes. More...

Detailed Description

Customization point for where TTS output actually goes.

All non-usage related output produced while running a test suite - tests progress, pass/fail/ fatal reports, additional logging information and the final results report - is written through the tts::output_handler currently in use, which itself forwards every message to an output_sink. Deriving from output_sink and overriding write() lets power users redirect that output wherever they need to: a file, a GUI widget, a socket, another logging system...

Example

#define TTS_MAIN
#define TTS_CUSTOM_DRIVER_FUNCTION custom_sink_main
#include <tts/tts.hpp>
 
// A power-user output_sink prefixing every message TTS writes before forwarding it to stdout.
struct prefixed_sink : tts::output_sink
{
  int  messages = 0;
 
  void write(tts::text const& t) override
  {
    messages++;
    if(t != "\n") fputs("[MY-TTS] ", stdout);
    fputs(t.data(), stdout);
  }
};
 
TTS_CASE("Some test running through our custom output_sink")
{
  TTS_EXPECT(1 == 1);
};
 
int main(int argc, char const** argv)
{
  ::tts::initialize(argc, argv);
 
  prefixed_sink sink;
  {
    tts::scoped_sink scope(sink); // Install our custom sink for this scope...
    custom_sink_main(argc, argv); // ...run the test suite through it...
  } // ...then automatically restore the previous one.
 
  printf("Our custom output_sink received %d message(s)\n", sink.messages);
 
  return tts::report(0, 0);
}

See also

tts::output_handler

tts::stdout_sink

tts::gathering_sink

Public Member Functions
virtual void	assertion_failed (text const &location, text const &message, bool fatal)
virtual void	finish ()
virtual void	flush ()
	Flushes this sink's destination, if that means anything for it. No-op by default.
virtual void	suite_aborted ()
virtual void	suite_finished (unsigned long long fail_count, unsigned long long invalid_count)
virtual void	suite_metric (outcome kind, unsigned long long count, unsigned long long total)
virtual void	test_finished (text const &name, bool passed, bool invalid, unsigned long long duration_ns)
virtual void	test_started (text const &name)
virtual void	write (text const &t)=0
	Writes t to this sink's destination.

Member Function Documentation

assertion_failed()

virtual void tts::output_sink::assertion_failed ( text const & location, text const & message, bool fatal )

inlinevirtual

Called once per failing/fatal assertion, always and before the corresponding text (if any - it's suppressed under -q for a plain failure, though never for a fatal one). No-op by default. Not called for passing assertions - test_finished()'s passed already covers that case, and most consumers of this hook don't want one event per assertion.

Reimplemented in tts::colorized_sink, tts::diagnostics_sink, tts::json_sink, and tts::junit_sink.

finish()

virtual void tts::output_sink::finish ( )

inlinevirtual

Called once, after tts::report() returns - every other hook has already fired by then - so an accumulate-style sink (e.g. tts::tap_sink) can render and flush its buffered content to its own destination. No-op by default: pass-through sinks that already forward write() as it happens (e.g. tts::colorized_sink) have nothing left to do here. Like --shard, this is only called by the default driver (TTS_MAIN) - a TTS_CUSTOM_DRIVER_FUNCTION manages whichever sink it installed itself, including dumping it, so its driver never calls finish() on its own.

Reimplemented in tts::json_sink, tts::junit_sink, and tts::tap_sink.

suite_aborted()

virtual void tts::output_sink::suite_aborted ( )

inlinevirtual

Called if the suite aborts early due to a TTS_FATAL failure, before tts::report() (and thus suite_finished()) runs. No-op by default.

Reimplemented in tts::colorized_sink.

suite_finished()

virtual void tts::output_sink::suite_finished ( unsigned long long fail_count, unsigned long long invalid_count )

inlinevirtual

Called once the whole suite has finished running (from tts::report()), with its aggregate outcome, always - even under -q. No-op by default.

Reimplemented in tts::colorized_sink.

suite_metric()

virtual void tts::output_sink::suite_metric ( outcome kind, unsigned long long count, unsigned long long total )

inlinevirtual

Called once per non-zero outcome category, right before its "N/M (P%) <label>" segment is printed as part of the Results: ... summary. No-op by default.

Reimplemented in tts::colorized_sink.

test_finished()

virtual void tts::output_sink::test_finished ( text const & name, bool passed, bool invalid, unsigned long long duration_ns )

inlinevirtual

Called once a TTS_CASE / TTS_CASE_TPL / TTS_CASE_WITH has finished running, always and before its corresponding text (if any - suppressed under -q), with its outcome and how long it took to run, in nanoseconds. No-op by default.

Reimplemented in tts::colorized_sink, tts::json_sink, tts::junit_sink, and tts::tap_sink.

test_started()

virtual void tts::output_sink::test_started ( text const & name )

inlinevirtual

Called when a TTS_CASE / TTS_CASE_TPL / TTS_CASE_WITH is about to run. No-op by default - opt-in for sinks that want structured per-test events instead of (or in addition to) parsing the formatted text stream.

Reimplemented in tts::colorized_sink.