Deterministic validation harness. More...

#include <validation_harness.hpp>

Public Types
using	CaptureScreenshotProvider
	Callback that captures a screenshot of the current view/render state into output_path.
using	CaptureInspectorProvider = std::function<std::string()>
	Callback that produces a JSON snapshot of the view tree.

Public Member Functions
	ValidationHarness (ProcessorFactory factory)
	Construct from a processor factory.
void	configure (const ValidationRunOptions &opts)
	Configure the harness with run options.
void	prepare ()
	Prepare the processor for audio. Uses options from configure().
void	set_param (state::ParamID id, float value)
	Set a parameter value by ID.
float	get_param (state::ParamID id) const
	Get a parameter value by ID.
void	send_midi_note_on (int channel, int note, int velocity)
	Send MIDI note-on into the next process() call.
void	send_midi_note_off (int channel, int note)
	Send MIDI note-off into the next process() call.
void	send_midi_cc (int channel, int controller, int value)
	Send MIDI CC into the next process() call.
std::vector< float >	process_blocks (int num_blocks)
	Process N blocks of silence, returning the final output buffer contents.
std::vector< float >	process_buffer (const std::vector< float > &interleaved_input, int num_channels, int num_samples)
	Process a single block of audio from the given input buffer.
std::vector< double >	process_buffer_f64 (const std::vector< double > &interleaved_input, int num_channels, int num_samples)
	Process a single double-precision block from the given input buffer.
std::vector< uint8_t >	save_state () const
	Save current plugin state to a binary blob.
bool	load_state (std::span< const uint8_t > data)
	Load plugin state from a binary blob.
void	set_capture_screenshot_provider (CaptureScreenshotProvider p)
	Install the screenshot capture provider.
void	set_capture_inspector_provider (CaptureInspectorProvider p)
	Install the inspector capture provider.
ReportEntry	capture_screenshot (const std::filesystem::path &output_path)
	Capture a screenshot to the given path.
ReportEntry	compare_screenshots (const std::filesystem::path &reference, const std::filesystem::path &rendered)
	Compare two screenshot files and generate a diff entry.
ReportEntry	capture_inspector ()
	Capture the view inspector tree as JSON.
ReportEntry	run_validator (const std::string &tool, const std::filesystem::path &plugin_path, const std::string &format="")
	Run an external validator tool on a plugin bundle.
ReportEntry	validate_plugin_runtime_manifest (const std::filesystem::path &plugin_path, const std::string &expected_plugin_id="")
	Validate the embedded plugin runtime manifest for content-pack support.
ReportEntry	record_runtime_overload (const audio::AudioProcessLoadSnapshot &load, std::uint64_t xrun_count, const audio::AudioRuntimeOverloadPolicy &policy={})
	Record runtime load/xrun telemetry using the shared overload policy.
void	add_entry (ReportEntry entry)
	Add a report entry to the accumulator.
std::string	generate_report () const
	Generate the full validation report as JSON (conforming to schema v1).
bool	write_report (const std::filesystem::path &output_path) const
	Write the report JSON to a file.
const std::vector< ReportEntry > &	entries () const
	Get all accumulated report entries.
void	clear_entries ()
	Clear all accumulated entries.
HeadlessHost &	host ()
	Access the underlying HeadlessHost for advanced use.
const HeadlessHost &	host () const
const PluginDescriptor &	descriptor () const
	Access the plugin descriptor.

Detailed Description

Deterministic validation harness.

Wraps HeadlessHost with screenshot, inspector, and report generation to provide a single stable control surface for validation workflows.

ValidationHarness harness(MyPlugin::create);
harness.prepare();
harness.set_param(kGain, -6.0f);
harness.process_blocks(10);
harness.capture_screenshot("/tmp/shot.png");
auto report = harness.generate_report();

Member Typedef Documentation

◆ CaptureInspectorProvider

using pulp::format::ValidationHarness::CaptureInspectorProvider = std::function<std::string()>

Callback that produces a JSON snapshot of the view tree.

Returns the JSON string; empty string means "no tree available".

◆ CaptureScreenshotProvider

using pulp::format::ValidationHarness::CaptureScreenshotProvider

Initial value:

 std::function<bool(
        const std::filesystem::path& output_path,
        uint32_t width, uint32_t height, float scale,
        const std::string& backend)>

Callback that captures a screenshot of the current view/render state into output_path.

Returns true on success.

Constructor & Destructor Documentation

◆ ValidationHarness()

pulp::format::ValidationHarness::ValidationHarness ( ProcessorFactory factory )

explicit

Construct from a processor factory.

Member Function Documentation

◆ add_entry()

void pulp::format::ValidationHarness::add_entry ( ReportEntry entry )

Add a report entry to the accumulator.

◆ capture_inspector()

ReportEntry pulp::format::ValidationHarness::capture_inspector ( )

Capture the view inspector tree as JSON.

Returns a ReportEntry. Requires a capture-inspector provider installed via set_capture_inspector_provider(); otherwise reports skip.

◆ capture_screenshot()

ReportEntry pulp::format::ValidationHarness::capture_screenshot ( const std::filesystem::path & output_path )

Capture a screenshot to the given path.

Returns a ReportEntry. Requires a capture-screenshot provider installed via set_capture_screenshot_provider(); otherwise reports skip.

◆ clear_entries()

void pulp::format::ValidationHarness::clear_entries ( )

inline

Clear all accumulated entries.

◆ compare_screenshots()

ReportEntry pulp::format::ValidationHarness::compare_screenshots	(	const std::filesystem::path &	reference,
		const std::filesystem::path &	rendered )

Compare two screenshot files and generate a diff entry.

Today this does a byte-level file comparison — pixel-level diffing (with a tolerance) requires a PNG codec in the format layer. A real pixel diff always produces pass/fail, never skip.

◆ configure()

void pulp::format::ValidationHarness::configure ( const ValidationRunOptions & opts )

Configure the harness with run options.

◆ descriptor()

const PluginDescriptor & pulp::format::ValidationHarness::descriptor ( ) const

inline

Access the plugin descriptor.

◆ entries()

const std::vector< ReportEntry > & pulp::format::ValidationHarness::entries ( ) const

inline

Get all accumulated report entries.

◆ generate_report()

std::string pulp::format::ValidationHarness::generate_report ( ) const

Generate the full validation report as JSON (conforming to schema v1).

◆ get_param()

float pulp::format::ValidationHarness::get_param ( state::ParamID id ) const

Get a parameter value by ID.

◆ host() [1/2]

HeadlessHost & pulp::format::ValidationHarness::host ( )

inline

Access the underlying HeadlessHost for advanced use.

◆ host() [2/2]

const HeadlessHost & pulp::format::ValidationHarness::host ( ) const

inline

◆ load_state()

bool pulp::format::ValidationHarness::load_state ( std::span< const uint8_t > data )

Load plugin state from a binary blob.

◆ prepare()

void pulp::format::ValidationHarness::prepare ( )

Prepare the processor for audio. Uses options from configure().

◆ process_blocks()

std::vector< float > pulp::format::ValidationHarness::process_blocks ( int num_blocks )

Process N blocks of silence, returning the final output buffer contents.

Useful for letting tail ring out or stabilising state.

◆ process_buffer()

std::vector< float > pulp::format::ValidationHarness::process_buffer	(	const std::vector< float > &	interleaved_input,
		int	num_channels,
		int	num_samples )

Process a single block of audio from the given input buffer.

Input is interleaved: [ch0_s0, ch1_s0, ch0_s1, ch1_s1, ...]. Returns interleaved output.

◆ process_buffer_f64()

std::vector< double > pulp::format::ValidationHarness::process_buffer_f64	(	const std::vector< double > &	interleaved_input,
		int	num_channels,
		int	num_samples )

Process a single double-precision block from the given input buffer.

Input is interleaved: [ch0_s0, ch1_s0, ch0_s1, ch1_s1, ...]. Returns interleaved double-precision output.

◆ record_runtime_overload()

ReportEntry pulp::format::ValidationHarness::record_runtime_overload	(	const audio::AudioProcessLoadSnapshot &	load,
		std::uint64_t	xrun_count,
		const audio::AudioRuntimeOverloadPolicy &	policy = {} )

Record runtime load/xrun telemetry using the shared overload policy.

◆ run_validator()

ReportEntry pulp::format::ValidationHarness::run_validator	(	const std::string &	tool,
		const std::filesystem::path &	plugin_path,
		const std::string &	format = "" )

Run an external validator tool on a plugin bundle.

Supported tools: "pluginval", "clap-validator", "auval", "vstvalidator". Returns skip status if the tool is not installed.

◆ save_state()

std::vector< uint8_t > pulp::format::ValidationHarness::save_state ( ) const

Save current plugin state to a binary blob.

◆ send_midi_cc()

void pulp::format::ValidationHarness::send_midi_cc	(	int	channel,
		int	controller,
		int	value )

Send MIDI CC into the next process() call.

◆ send_midi_note_off()

void pulp::format::ValidationHarness::send_midi_note_off	(	int	channel,
		int	note )

Send MIDI note-off into the next process() call.

◆ send_midi_note_on()

void pulp::format::ValidationHarness::send_midi_note_on	(	int	channel,
		int	note,
		int	velocity )

Send MIDI note-on into the next process() call.

◆ set_capture_inspector_provider()

void pulp::format::ValidationHarness::set_capture_inspector_provider ( CaptureInspectorProvider p )

Install the inspector capture provider.

◆ set_capture_screenshot_provider()

void pulp::format::ValidationHarness::set_capture_screenshot_provider ( CaptureScreenshotProvider p )

Install the screenshot capture provider.

Pass an empty std::function to remove.

◆ set_param()

void pulp::format::ValidationHarness::set_param	(	state::ParamID	id,
		float	value )

Set a parameter value by ID.

◆ validate_plugin_runtime_manifest()

ReportEntry pulp::format::ValidationHarness::validate_plugin_runtime_manifest	(	const std::filesystem::path &	plugin_path,
		const std::string &	expected_plugin_id = "" )

Validate the embedded plugin runtime manifest for content-pack support.

Looks for pulp.plugin-runtime.json in the bundle resource convention: Contents/Resources/ first (VST3/AU/macOS bundles), then Resources/, then the bundle root. Single-file plugin paths may also use a sibling <plugin-stem>.pulp.plugin-runtime.json sidecar for validation fixtures and non-bundle formats.

If expected_plugin_id is empty, the harness compares the manifest pluginId against the processor descriptor's bundle_id.

◆ write_report()

bool pulp::format::ValidationHarness::write_report ( const std::filesystem::path & output_path ) const

Write the report JSON to a file.

The documentation for this class was generated from the following file:

/home/runner/work/pulp/pulp/core/format/include/pulp/format/validation_harness.hpp

Pulp 1.88.0 Cross-platform audio plugin framework

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ CaptureInspectorProvider

◆ CaptureScreenshotProvider

Constructor & Destructor Documentation

◆ ValidationHarness()

Member Function Documentation

◆ add_entry()

◆ capture_inspector()

◆ capture_screenshot()

◆ clear_entries()

◆ compare_screenshots()

◆ configure()

◆ descriptor()

◆ entries()

◆ generate_report()

◆ get_param()

◆ host() [1/2]

◆ host() [2/2]

◆ load_state()

◆ prepare()

◆ process_blocks()

◆ process_buffer()

◆ process_buffer_f64()

◆ record_runtime_overload()

◆ run_validator()

◆ save_state()

◆ send_midi_cc()

◆ send_midi_note_off()

◆ send_midi_note_on()

◆ set_capture_inspector_provider()

◆ set_capture_screenshot_provider()

◆ set_param()

◆ validate_plugin_runtime_manifest()

◆ write_report()