FrozenBaselinePolicy.h File Reference

What a run does when it is on an adapter that has no committed pixel baseline. More...

#include <ostream>
#include <span>
#include <string>
#include <string_view>

Include dependency graph for FrozenBaselinePolicy.h:

Namespaces
namespace	donner
	Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css.

Enumerations
enum class	donner::gpu::baseline::MissingComparisonDisposition {   Skip ,   FailClosed }
	What a run should do when it cannot perform the comparison it exists to perform. More...

Functions
std::ostream &	donner::gpu::baseline::operator<< (std::ostream &os, MissingComparisonDisposition disposition)
	Streams the disposition name.
std::span< const std::string_view >	donner::gpu::baseline::ContinuousIntegrationMarkers ()
	Environment variables whose presence marks an automated lane.
bool	donner::gpu::baseline::AnyEnvironmentVariableIsSet (std::span< const std::string_view > names)
	Whether any of names is set to a non-empty value in the process environment.
bool	donner::gpu::baseline::RunningUnderContinuousIntegration ()
	Whether this process is running on an automated lane.
std::string	donner::gpu::baseline::AdapterSlug (std::string_view adapterName, std::string_view adapterBackend)
	Directory name the baselines for one adapter are filed under, for example apple_m1_pro_metal.
MissingComparisonDisposition	donner::gpu::baseline::DispositionForMissingAdapter (bool underContinuousIntegration)
	The disposition for a run that cannot create a GPU device at all.
MissingComparisonDisposition	donner::gpu::baseline::DispositionForUnbaselinedAdapter (bool underContinuousIntegration)
	The disposition for an adapter with no committed baseline.
std::string	donner::gpu::baseline::UnbaselinedAdapterMessage (std::string_view adapterName, std::string_view adapterBackend, std::string_view slug, std::string_view capturedPath, std::string_view captureError, MissingComparisonDisposition disposition)
	The message a run reports when its adapter has no committed baseline.
std::string	donner::gpu::baseline::NoAdapterMessage (std::string_view gateLabel, MissingComparisonDisposition disposition)
	The message a run reports when it cannot create a GPU device.

Detailed Description

What a run does when it is on an adapter that has no committed pixel baseline.

The two answers are not interchangeable. A person running the check locally on new hardware wants the capture handed to them so they can commit it; an automated lane that quietly skips instead is a gate that never runs, and a suite reporting success while asserting nothing is worse than no suite at all. The decision lives here, apart from the GPU-bound test, so it is exercised without a device on every platform.

Enumeration Type Documentation

MissingComparisonDisposition

enum class donner::gpu::baseline::MissingComparisonDisposition

strong

What a run should do when it cannot perform the comparison it exists to perform.

Enumerator
Skip	Report the case as skipped, leaving any artifact a person needs.
FailClosed	Fail: skipping here would silently retire the gate.

Function Documentation

AdapterSlug()

std::string donner::gpu::baseline::AdapterSlug	(	std::string_view	adapterName,
		std::string_view	adapterBackend )

Directory name the baselines for one adapter are filed under, for example apple_m1_pro_metal.

Lowercase, with every run of non-alphanumeric characters collapsed to one underscore, so one adapter always resolves to one directory on every platform.

This lives here rather than beside the capture library because both sides need it and only one of them can link the capture library: the wgpu-backed capture writes these directories, and the per-backend vertical slices, which deliberately carry no wgpu dependency, read them.

Parameters

adapterName	Vendor and device string the driver reports.
adapterBackend	Backend name, for example Metal or Vulkan.

Returns

The directory name, or unknown_adapter when the inputs carry no alphanumerics.

AnyEnvironmentVariableIsSet()

bool donner::gpu::baseline::AnyEnvironmentVariableIsSet

(

std::span< const std::string_view >

names

)

Whether any of names is set to a non-empty value in the process environment.

Parameters

names

Environment variable names to check.

Returns

True when at least one is present and non-empty.

ContinuousIntegrationMarkers()

std::span< const std::string_view > donner::gpu::baseline::ContinuousIntegrationMarkers

(

)

Environment variables whose presence marks an automated lane.

GITHUB_ACTIONS is set by the hosted runner itself. The Donner-specific name lets any other automated lane opt in without this list having to learn every runner's convention.

Returns

The marker names, in a stable order.

DispositionForMissingAdapter()

MissingComparisonDisposition donner::gpu::baseline::DispositionForMissingAdapter

(

bool

underContinuousIntegration

)

The disposition for a run that cannot create a GPU device at all.

A missing device is not the same situation as a missing baseline, but it has the same consequence: the comparison does not happen. On a developer machine without a working driver that is a skip. On an automated lane it is a failure, because a lane selected this target and then compared nothing, and a driver or runner regression that silently disables a gate is indistinguishable from the gate passing.

Parameters

underContinuousIntegration

Whether this process is on an automated lane.

Returns

What the run should do.

DispositionForUnbaselinedAdapter()

MissingComparisonDisposition donner::gpu::baseline::DispositionForUnbaselinedAdapter

(

bool

underContinuousIntegration

)

The disposition for an adapter with no committed baseline.

Parameters

underContinuousIntegration

Whether this process is on an automated lane.

Returns

What the run should do.

NoAdapterMessage()

std::string donner::gpu::baseline::NoAdapterMessage	(	std::string_view	gateLabel,
		MissingComparisonDisposition	disposition )

The message a run reports when it cannot create a GPU device.

Parameters

gateLabel	What the gate is, for a reader who sees only this line.
disposition	What the run is about to do.

Returns

A message naming the gate and, when failing, why skipping was not an option.

operator<<()

std::ostream & donner::gpu::baseline::operator<<	(	std::ostream &	os,
		MissingComparisonDisposition	disposition )

Streams the disposition name.

Parameters

os	Stream.
disposition	Value.

Returns

os.

RunningUnderContinuousIntegration()

bool donner::gpu::baseline::RunningUnderContinuousIntegration

(

)

Whether this process is running on an automated lane.

Returns

True on such a lane.

UnbaselinedAdapterMessage()

std::string donner::gpu::baseline::UnbaselinedAdapterMessage	(	std::string_view	adapterName,
		std::string_view	adapterBackend,
		std::string_view	slug,
		std::string_view	capturedPath,
		std::string_view	captureError,
		MissingComparisonDisposition	disposition )

The message a run reports when its adapter has no committed baseline.

Parameters

adapterName	Live adapter name.
adapterBackend	Live adapter backend.
slug	Directory name the baseline for this adapter belongs in.
capturedPath	Where this run left a capture, empty when none was written.
captureError	Why the capture failed, empty on success.
disposition	What the run is about to do.

Returns

A message naming what to commit and, when failing, why skipping was not an option.