use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
use crate::evidence::cast_video::{append_checkpoint_frames, CastVideoConverter};
use crate::evidence::dedup::Deduper;
use crate::evidence::screenshot::ScreenshotRenderer;
use crate::evidence::uploader::ArtifactUploader;
use crate::result::RunResult;
use crate::store::{atomic_write_text, sanitize_component};
use crate::terminal::attributed::{
attributed_screen_from_text, AttributedScreen, DEFAULT_COLUMNS, DEFAULT_ROWS,
};
use crate::terminal::session::Session;
pub const EVIDENCE_MANIFEST_VERSION: u32 = 1;
pub const MANIFEST_FILE: &str = "evidence.json";
const MAX_LABEL_IN_FILENAME: usize = 40;
const STEP_SAVE_CAST: &str = "save cast";
const STEP_APPEND_FRAMES: &str = "append checkpoint frames";
const STEP_CONVERT: &str = "convert";
const STEP_UPLOAD: &str = "upload";
const NO_VIDEO_CONVERTER: &str = "no video converter configured";
const NO_URL: &str = "uploader returned no URL";
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RawOutput {
Keep,
Skip,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ScreenCapture {
pub screen: String,
pub attributed: Option<AttributedScreen>,
pub raw_output: Option<String>,
}
pub trait ScreenSource {
fn capture_screen(&mut self, raw: RawOutput) -> ScreenCapture;
}
impl<T: Session + ?Sized> ScreenSource for T {
fn capture_screen(&mut self, raw: RawOutput) -> ScreenCapture {
let attributed = Session::screen_attributed(self);
let screen = match &attributed {
Some(grid) => grid_text(grid),
None => Session::screen(self).to_string(),
};
let raw_output = match raw {
RawOutput::Keep => Some(Session::raw_output(self).to_string()),
RawOutput::Skip => None,
};
ScreenCapture {
screen,
attributed,
raw_output,
}
}
}
fn grid_text(screen: &AttributedScreen) -> String {
let mut lines = screen.text_lines(true);
while lines.last().is_some_and(|line| line.is_empty()) {
lines.pop();
}
lines.join("\n")
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum CaptureKind {
Checkpoint,
Failure,
}
impl CaptureKind {
fn raw_output(self) -> RawOutput {
match self {
CaptureKind::Failure => RawOutput::Keep,
CaptureKind::Checkpoint => RawOutput::Skip,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CapturedStep {
pub index: usize,
pub label: String,
pub kind: CaptureKind,
pub screen: String,
pub attributed: AttributedScreen,
pub raw_output: Option<String>,
}
impl CapturedStep {
pub fn file_stem(&self) -> String {
let label: String = self.label.chars().take(MAX_LABEL_IN_FILENAME).collect();
format!("step-{:02}-{}", self.index, sanitize_component(&label))
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Recording {
pub label: String,
pub cast: String,
pub video: Option<String>,
pub url: Option<String>,
pub error: Option<String>,
}
impl Recording {
pub fn new(label: impl Into<String>, cast: impl Into<String>) -> Self {
Recording {
label: label.into(),
cast: cast.into(),
video: None,
url: None,
error: None,
}
}
pub fn with_video(mut self, video: impl Into<String>, url: Option<String>) -> Self {
self.video = Some(video.into());
self.url = url;
self
}
pub fn with_error(mut self, error: impl Into<String>) -> Self {
self.error = Some(error.into());
self
}
}
#[derive(Debug, Clone)]
pub struct EvidenceCollector {
steps: Vec<CapturedStep>,
recordings: Vec<Recording>,
columns: usize,
rows: usize,
}
impl Default for EvidenceCollector {
fn default() -> Self {
EvidenceCollector {
steps: Vec::new(),
recordings: Vec::new(),
columns: DEFAULT_COLUMNS,
rows: DEFAULT_ROWS,
}
}
}
impl EvidenceCollector {
pub fn new() -> Self {
Self::default()
}
pub fn with_grid(columns: usize, rows: usize) -> Self {
EvidenceCollector {
columns,
rows,
..Self::default()
}
}
pub fn capture<S: ScreenSource + ?Sized>(&mut self, label: &str, source: &mut S) {
self.record(label, CaptureKind::Checkpoint, source);
}
pub fn capture_failure<S: ScreenSource + ?Sized>(&mut self, label: &str, source: &mut S) {
self.record(label, CaptureKind::Failure, source);
}
pub fn capture_text(&mut self, label: &str, screen: &str, kind: CaptureKind) {
let attributed = attributed_screen_from_text(screen, self.columns, self.rows);
self.steps.push(CapturedStep {
index: self.steps.len(),
label: label.to_string(),
kind,
screen: screen.to_string(),
attributed,
raw_output: None,
});
}
fn record<S: ScreenSource + ?Sized>(&mut self, label: &str, kind: CaptureKind, source: &mut S) {
let capture = source.capture_screen(kind.raw_output());
let attributed = capture.attributed.unwrap_or_else(|| {
attributed_screen_from_text(&capture.screen, self.columns, self.rows)
});
self.steps.push(CapturedStep {
index: self.steps.len(),
label: label.to_string(),
kind,
screen: capture.screen,
attributed,
raw_output: capture.raw_output,
});
}
pub fn attach_recording(&mut self, recording: Recording) {
self.recordings.push(recording);
}
pub fn record_session<F>(
&mut self,
label: &str,
publisher: &mut EvidencePublisher,
save_cast: F,
) where
F: FnOnce(&Path) -> Result<(), String>,
{
let stem = recording_file_stem(self.recordings.len(), label);
let cast_path = publisher.dir.join(format!("{stem}.cast"));
let mut recording = Recording::new(label, path_string(&cast_path));
let mut errors: Vec<String> = Vec::new();
let saved = std::fs::create_dir_all(&publisher.dir)
.map_err(|e| e.to_string())
.and_then(|()| save_cast(&cast_path))
.and_then(|()| {
if cast_path.is_file() {
Ok(())
} else {
Err(format!(
"reported success but wrote no file at {}",
path_string(&cast_path)
))
}
});
if let Err(message) = saved {
recording.error = Some(format!("{STEP_SAVE_CAST}: {message}"));
self.recordings.push(recording);
return;
}
let cast_string = path_string(&cast_path);
if let Err(message) = append_checkpoint_frames(&cast_string, &self.steps, None) {
errors.push(format!("{STEP_APPEND_FRAMES}: {message}"));
}
let video_path = path_string(&publisher.dir.join(format!("{stem}.mp4")));
let converted = match &publisher.video_converter {
Some(converter) => {
converter
.convert(&cast_string, Some(&video_path))
.and_then(|video| {
if Path::new(&video).is_file() {
Ok(video)
} else {
Err(format!("reported success but wrote no file at {video}"))
}
})
}
None => Err(NO_VIDEO_CONVERTER.to_string()),
};
match converted {
Ok(video) => {
recording.video = Some(video.clone());
if let Some(uploader) = publisher.uploader.as_mut() {
match uploader.upload(&video).filter(|url| !url.is_empty()) {
Some(url) => recording.url = Some(url),
None => {
let detail = uploader
.last_error()
.filter(|e| !e.is_empty())
.unwrap_or(NO_URL);
errors.push(format!("{STEP_UPLOAD}: {detail}"));
}
}
}
}
Err(message) => errors.push(format!("{STEP_CONVERT}: {message}")),
}
if !errors.is_empty() {
recording.error = Some(errors.join("; "));
}
self.recordings.push(recording);
}
pub fn recordings(&self) -> &[Recording] {
&self.recordings
}
pub fn steps(&self) -> &[CapturedStep] {
&self.steps
}
pub fn len(&self) -> usize {
self.steps.len()
}
pub fn is_empty(&self) -> bool {
self.steps.is_empty()
}
pub fn publish(&self, publisher: &mut EvidencePublisher) -> Result<EvidenceManifest, String> {
let mut deduper = Deduper::default();
let mut last_rendered: Option<(ReusedFrom, String, Option<String>)> = None;
let mut published = Vec::with_capacity(self.steps.len());
for step in &self.steps {
let stem = step.file_stem();
let text_path = publisher.dir.join(format!("{stem}.txt"));
atomic_write_text(&text_path, &step.screen).map_err(|e| e.to_string())?;
let raw_output = match &step.raw_output {
Some(raw) => {
let raw_path = publisher.dir.join(format!("{stem}-raw.txt"));
atomic_write_text(&raw_path, raw).map_err(|e| e.to_string())?;
Some(path_string(&raw_path))
}
None => None,
};
let mut entry = PublishedStep {
index: step.index,
label: step.label.clone(),
kind: step.kind,
screen_text: path_string(&text_path),
raw_output,
screenshot: None,
url: None,
same_as: None,
error: None,
};
match deduper.check(&step.label, &step.attributed) {
Some(_) => {
if let Some((source, png, url)) = &last_rendered {
entry.same_as = Some(source.clone());
entry.screenshot = Some(png.clone());
entry.url = url.clone();
}
}
None => {
let png = path_string(&publisher.dir.join(format!("{stem}.png")));
match publisher
.renderer
.render(&step.screen, &png, Some(&step.attributed))
{
Ok(path) => {
let url = publisher.uploader.as_mut().and_then(|u| u.upload(&path));
entry.screenshot = Some(path.clone());
entry.url = url.clone();
last_rendered = Some((
ReusedFrom {
index: step.index,
label: step.label.clone(),
},
path,
url,
));
}
Err(message) => {
deduper.forget();
last_rendered = None;
entry.error = Some(message);
}
}
}
}
published.push(entry);
}
let manifest = EvidenceManifest {
manifest_version: EVIDENCE_MANIFEST_VERSION,
run: publisher.identity.clone(),
steps: published,
recordings: self.recordings.clone(),
path: publisher.manifest_path(),
};
atomic_write_text(&manifest.path, &manifest.to_json_pretty()).map_err(|e| e.to_string())?;
Ok(manifest)
}
}
fn recording_file_stem(index: usize, label: &str) -> String {
let label: String = label.chars().take(MAX_LABEL_IN_FILENAME).collect();
format!("recording-{:02}-{}", index, sanitize_component(&label))
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RunIdentity {
pub recipe_name: String,
pub renderer: String,
pub run_id: String,
}
impl RunIdentity {
pub fn new(
recipe_name: impl Into<String>,
renderer: impl Into<String>,
run_id: impl Into<String>,
) -> Self {
RunIdentity {
recipe_name: recipe_name.into(),
renderer: renderer.into(),
run_id: run_id.into(),
}
}
pub fn from_run_dir(run_dir: &Path, recipe_name: &str, renderer: &str) -> Self {
let run_id = run_dir
.file_name()
.map(|name| name.to_string_lossy().to_string())
.unwrap_or_default();
RunIdentity::new(recipe_name, renderer, run_id)
}
pub fn matches(&self, result: &RunResult) -> bool {
self.recipe_name == result.recipe_name && self.renderer == result.renderer
}
}
pub struct EvidencePublisher {
pub dir: PathBuf,
pub identity: RunIdentity,
pub renderer: ScreenshotRenderer,
pub uploader: Option<Box<dyn ArtifactUploader>>,
pub video_converter: Option<CastVideoConverter>,
}
impl std::fmt::Debug for EvidencePublisher {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("EvidencePublisher")
.field("dir", &self.dir)
.field("identity", &self.identity)
.field("uploader", &self.uploader.is_some())
.field("video_converter", &self.video_converter.is_some())
.finish()
}
}
impl EvidencePublisher {
pub fn new(dir: impl Into<PathBuf>, identity: RunIdentity) -> Self {
EvidencePublisher {
dir: dir.into(),
identity,
renderer: ScreenshotRenderer::new(),
uploader: None,
video_converter: None,
}
}
pub fn with_renderer(mut self, renderer: ScreenshotRenderer) -> Self {
self.renderer = renderer;
self
}
pub fn with_uploader(mut self, uploader: Box<dyn ArtifactUploader>) -> Self {
self.uploader = Some(uploader);
self
}
pub fn with_video_converter(mut self, converter: CastVideoConverter) -> Self {
self.video_converter = Some(converter);
self
}
pub fn manifest_path(&self) -> PathBuf {
self.dir.join(MANIFEST_FILE)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ReusedFrom {
pub index: usize,
pub label: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PublishedStep {
pub index: usize,
pub label: String,
pub kind: CaptureKind,
pub screen_text: String,
pub raw_output: Option<String>,
pub screenshot: Option<String>,
pub url: Option<String>,
pub same_as: Option<ReusedFrom>,
pub error: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct EvidenceManifest {
pub manifest_version: u32,
pub run: RunIdentity,
pub steps: Vec<PublishedStep>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub recordings: Vec<Recording>,
#[serde(skip)]
path: PathBuf,
}
impl EvidenceManifest {
pub fn path(&self) -> &Path {
&self.path
}
pub fn attach_to(&self, result: &mut RunResult) -> Result<(), String> {
if !self.run.matches(result) {
return Err(format!(
"evidence for {}/{} cannot be attached to a result for {}/{}",
self.run.recipe_name, self.run.renderer, result.recipe_name, result.renderer,
));
}
result.artifacts.extend(self.artifacts());
Ok(())
}
pub fn artifacts(&self) -> BTreeMap<String, String> {
BTreeMap::from([("evidence_manifest".to_string(), path_string(&self.path))])
}
pub fn deduped(&self) -> impl Iterator<Item = &PublishedStep> {
self.steps.iter().filter(|s| s.same_as.is_some())
}
pub fn to_json_pretty(&self) -> String {
let mut s = serde_json::to_string_pretty(self).expect("EvidenceManifest is serializable");
s.push('\n');
s
}
}
fn path_string(path: &Path) -> String {
path.to_string_lossy().to_string()
}
#[cfg(test)]
mod tests {
use std::sync::{Arc, Mutex};
use super::*;
use crate::terminal::attributed::attributed_screen_from_ansi_text;
use crate::terminal::inmemory::InMemorySession;
use crate::terminal::screen::TerminalScreen;
struct Replay {
frames: Vec<String>,
at: usize,
}
impl ScreenSource for Replay {
fn capture_screen(&mut self, raw: RawOutput) -> ScreenCapture {
let screen = self.frames[self.at].clone();
self.at += 1;
ScreenCapture {
screen,
attributed: None,
raw_output: match raw {
RawOutput::Keep => Some(self.frames[..self.at].join("")),
RawOutput::Skip => None,
},
}
}
}
struct DriftingSession {
snapshot: InMemorySession,
live: &'static str,
}
impl DriftingSession {
fn new(stale: &str, live: &'static str) -> Self {
let mut snapshot = InMemorySession::new(vec![], PathBuf::from("/tmp/x.cast"), 80, 24);
snapshot.set_screen(stale);
DriftingSession { snapshot, live }
}
}
impl Session for DriftingSession {
fn send_text(&mut self, t: &str) -> Result<(), crate::terminal::error::SessionError> {
self.snapshot.send_text(t)
}
fn send_line(&mut self, t: &str) -> Result<(), crate::terminal::error::SessionError> {
self.snapshot.send_line(t)
}
fn press(&mut self, k: &str) -> Result<(), crate::terminal::error::SessionError> {
self.snapshot.press(k)
}
fn wait_for_text(
&mut self,
t: &str,
d: std::time::Duration,
) -> Result<bool, crate::terminal::error::SessionError> {
self.snapshot.wait_for_text(t, d)
}
fn wait_for_idle(
&mut self,
s: std::time::Duration,
t: std::time::Duration,
) -> Result<bool, crate::terminal::error::SessionError> {
self.snapshot.wait_for_idle(s, t)
}
fn wait_for_exit(
&mut self,
t: std::time::Duration,
) -> Result<Option<i32>, crate::terminal::error::SessionError> {
self.snapshot.wait_for_exit(t)
}
fn read_available(
&mut self,
t: std::time::Duration,
) -> Result<(), crate::terminal::error::SessionError> {
self.snapshot.read_available(t)
}
fn is_alive(&mut self) -> bool {
self.snapshot.is_alive()
}
fn close(&mut self) -> Result<(), crate::terminal::error::SessionError> {
self.snapshot.close()
}
fn screen(&self) -> &str {
self.snapshot.screen()
}
fn screen_attributed(&mut self) -> Option<AttributedScreen> {
Some(attributed_screen_from_text(self.live, 80, 24))
}
fn raw_output(&self) -> &str {
self.snapshot.raw_output()
}
fn exit_code(&self) -> Option<i32> {
self.snapshot.exit_code()
}
fn cols(&self) -> u16 {
self.snapshot.cols()
}
fn rows(&self) -> u16 {
self.snapshot.rows()
}
fn argv(&self) -> &[String] {
self.snapshot.argv()
}
fn cast_path(&self) -> &Path {
self.snapshot.cast_path()
}
}
fn session(screen: &str) -> InMemorySession {
let mut s = InMemorySession::new(vec![], PathBuf::from("/tmp/x.cast"), 80, 24);
s.set_screen(screen);
s
}
fn identity() -> RunIdentity {
RunIdentity::new("login", "default", "20240101-000000-000000-login-default-1")
}
fn run_result(recipe_name: &str, renderer: &str) -> RunResult {
RunResult {
result_version: Some(crate::result::RESULT_SCHEMA_VERSION),
recipe_name: recipe_name.to_string(),
passed: true,
exit_code: Some(0),
duration_seconds: 1.0,
priority: "P0".to_string(),
execution: "scripted".to_string(),
renderer: renderer.to_string(),
score: 1.0,
steps: vec![],
assertions: vec![],
artifacts: BTreeMap::new(),
}
}
fn publisher(dir: &Path) -> EvidencePublisher {
EvidencePublisher::new(dir, identity()).with_renderer(ScreenshotRenderer::with_runner(
Box::new(|_, args, _| std::fs::write(&args[1], b"png").map_err(|e| e.to_string())),
))
}
fn counting_publisher(dir: &Path) -> (EvidencePublisher, Arc<Mutex<Vec<String>>>) {
let seen = Arc::new(Mutex::new(Vec::new()));
let sink = seen.clone();
let publisher = EvidencePublisher::new(dir, identity()).with_renderer(
ScreenshotRenderer::with_runner(Box::new(move |_, args, _| {
sink.lock().expect("poisoned").push(args[1].clone());
std::fs::write(&args[1], b"png").map_err(|e| e.to_string())
})),
);
(publisher, seen)
}
#[test]
fn a_session_is_a_screen_source_without_implementing_anything() {
let mut owned = session("menu");
let mut collector = EvidenceCollector::new();
collector.capture("owned", &mut owned);
let mut boxed: Box<dyn Session> = Box::new(session("menu"));
collector.capture("dyn", boxed.as_mut());
let mut driver = crate::terminal::driver::SessionDriver::new(Box::new(session("menu")));
collector.capture("driver", driver.session_mut());
assert_eq!(collector.len(), 3);
assert!(collector.steps().iter().all(|s| s.screen == "menu"));
}
#[test]
fn text_and_grid_describe_the_same_instant() {
let mut drifting = DriftingSession::new("before", "after");
let mut collector = EvidenceCollector::new();
collector.capture("mid-flight", &mut drifting);
let step = &collector.steps()[0];
assert_eq!(step.screen, "after");
assert_eq!(step.attributed.to_text(true), "after");
}
#[test]
fn grid_text_matches_what_a_session_reports_as_its_screen() {
let mut screen = TerminalScreen::new(80, 24);
screen.feed_str("hello\r\n world \r\n");
assert_eq!(grid_text(&screen.attributed()), screen.contents());
let mut empty = TerminalScreen::new(80, 24);
empty.feed_str("");
assert_eq!(grid_text(&empty.attributed()), empty.contents());
}
#[test]
fn a_non_session_source_can_be_captured() {
let mut replay = Replay {
frames: vec!["one".into(), "two".into()],
at: 0,
};
let mut collector = EvidenceCollector::new();
collector.capture("first", &mut replay);
collector.capture("second", &mut replay);
let screens: Vec<&str> = collector
.steps()
.iter()
.map(|s| s.screen.as_str())
.collect();
assert_eq!(screens, ["one", "two"]);
}
#[test]
fn text_can_be_captured_without_a_source() {
let mut s = session("live");
let mut collector = EvidenceCollector::new();
collector.capture("from-session", &mut s);
collector.capture_text("from-log", "recovered", CaptureKind::Checkpoint);
collector.capture_text("post-mortem", "last screen", CaptureKind::Failure);
let steps = collector.steps();
assert_eq!(steps.len(), 3);
assert_eq!(steps[1].index, 1);
assert_eq!(steps[1].screen, "recovered");
assert_eq!(steps[1].attributed.to_text(true), "recovered");
assert_eq!(steps[2].kind, CaptureKind::Failure);
assert!(steps[2].raw_output.is_none());
}
#[test]
fn recordings_reach_the_manifest_alongside_the_steps() {
let dir = tempfile::tempdir().unwrap();
let mut s = session("screen");
let mut collector = EvidenceCollector::new();
collector.capture("one", &mut s);
collector.attach_recording(
Recording::new("full-session", "/tmp/session.cast")
.with_video("/tmp/session.mp4", Some("https://x/v".into())),
);
let mut publisher = EvidencePublisher::new(dir.path(), identity());
let manifest = collector.publish(&mut publisher).unwrap();
assert_eq!(1, manifest.steps.len());
assert_eq!(1, manifest.recordings.len());
assert_eq!("full-session", manifest.recordings[0].label);
assert_eq!(Some("https://x/v".to_string()), manifest.recordings[0].url);
assert!(manifest.to_json_pretty().contains("\"recordings\""));
}
#[test]
fn a_run_with_no_recordings_writes_the_document_it_always_wrote() {
let dir = tempfile::tempdir().unwrap();
let mut s = session("screen");
let mut collector = EvidenceCollector::new();
collector.capture("one", &mut s);
let mut publisher = EvidencePublisher::new(dir.path(), identity());
let manifest = collector.publish(&mut publisher).unwrap();
assert!(manifest.recordings.is_empty());
assert!(!manifest.to_json_pretty().contains("recordings"));
}
#[test]
fn a_recording_carries_why_it_produced_no_video() {
let recording =
Recording::new("full-session", "/tmp/s.cast").with_error("video conversion failed");
assert!(recording.video.is_none());
assert!(recording.url.is_none());
assert_eq!(Some("video conversion failed".to_string()), recording.error);
}
#[test]
fn a_recordings_debug_reaches_nothing_but_its_own_strings() {
let recording = Recording::new("full-session", "/tmp/s.cast")
.with_video("/tmp/s.mp4", Some("https://x/v".to_string()));
assert_eq!(
format!("{recording:?}"),
r#"Recording { label: "full-session", cast: "/tmp/s.cast", video: Some("/tmp/s.mp4"), url: Some("https://x/v"), error: None }"#
);
}
const A_CAST: &str = "{\"version\":2,\"width\":10,\"height\":3}\n[0.5,\"o\",\"live\"]\n";
fn save_a_cast(dest: &Path) -> Result<(), String> {
std::fs::write(dest, A_CAST).map_err(|e| e.to_string())
}
fn stub_converter() -> CastVideoConverter {
CastVideoConverter::with_runner(Box::new(|exe, args, _| {
let (path, bytes): (&String, &[u8]) = if exe.ends_with("ffmpeg") {
(args.last().ok_or("stub: no output")?, b"mp4")
} else {
let at = args
.iter()
.position(|a| a == "--output")
.ok_or("stub: no --output")?;
(args.get(at + 1).ok_or("stub: no output")?, b"png")
};
std::fs::write(path, bytes).map_err(|e| e.to_string())
}))
}
fn broken_converter() -> CastVideoConverter {
CastVideoConverter::with_runner(Box::new(|_, _, _| Err("encoder exploded".to_string())))
}
fn silent_converter() -> CastVideoConverter {
CastVideoConverter::with_runner(Box::new(|_, _, _| Ok(())))
}
struct CountingUploader(Arc<Mutex<Vec<String>>>);
impl ArtifactUploader for CountingUploader {
fn upload(&mut self, path: &str) -> Option<String> {
self.0.lock().expect("poisoned").push(path.to_string());
Some("https://example/video".to_string())
}
fn last_error(&self) -> Option<&str> {
None
}
}
fn one_capture() -> EvidenceCollector {
let mut collector = EvidenceCollector::new();
collector.capture("only", &mut session("screen text"));
collector
}
#[test]
fn every_public_field_of_the_publisher_is_accounted_for() {
let publisher = EvidencePublisher {
dir: PathBuf::from("/tmp/evidence"),
identity: identity(),
renderer: ScreenshotRenderer::new(),
uploader: None,
video_converter: None,
};
assert_eq!(publisher.dir, PathBuf::from("/tmp/evidence"));
assert!(publisher.uploader.is_none());
assert!(publisher.video_converter.is_none());
}
#[test]
fn the_semver_waiver_is_scoped_to_the_release_it_was_granted_for() {
let manifest = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/Cargo.toml"));
let waived = manifest.contains("constructible_struct_adds_field");
let version = env!("CARGO_PKG_VERSION");
assert!(
!waived || version.starts_with("0.4."),
"the constructible_struct_adds_field waiver in Cargo.toml was granted \
for 0.4.x and this crate is {version}. Re-decide it: either the break \
is now carried by the version bump and the waiver, its comment and \
`every_public_field_of_the_publisher_is_accounted_for` all go, or it \
is re-granted for the new line and this test moves with it."
);
}
#[test]
fn record_session_runs_the_five_steps_in_order() {
let dir = tempfile::tempdir().expect("tempdir");
let uploaded = Arc::new(Mutex::new(Vec::new()));
let mut publisher = publisher(dir.path())
.with_video_converter(stub_converter())
.with_uploader(Box::new(CountingUploader(uploaded.clone())));
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, save_a_cast);
let recording = &collector.recordings()[0];
assert_eq!(recording.label, "full-session");
assert_eq!(recording.error, None);
let cast = Path::new(&recording.cast);
assert!(cast.exists(), "{:?}", recording.cast);
assert_eq!(
cast.file_name().map(|n| n.to_string_lossy().to_string()),
Some("recording-00-full-session.cast".to_string())
);
let contents = std::fs::read_to_string(cast).expect("cast readable");
assert!(contents.starts_with(A_CAST), "the session's cast is intact");
assert!(contents.contains("screen text"), "{contents}");
let video = recording.video.as_deref().expect("video");
assert!(video.ends_with("recording-00-full-session.mp4"), "{video}");
assert_eq!(std::fs::read_to_string(video).expect("video"), "mp4");
assert_eq!(recording.url.as_deref(), Some("https://example/video"));
assert_eq!(*uploaded.lock().expect("poisoned"), vec![video.to_string()]);
let manifest = collector.publish(&mut publisher).expect("published");
assert_eq!(manifest.recordings, collector.recordings());
}
#[test]
fn a_cast_that_cannot_be_saved_stops_the_sequence() {
let dir = tempfile::tempdir().expect("tempdir");
let uploaded = Arc::new(Mutex::new(Vec::new()));
let mut publisher = publisher(dir.path())
.with_video_converter(stub_converter())
.with_uploader(Box::new(CountingUploader(uploaded.clone())));
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, |_| {
Err("disk on fire".to_string())
});
let recording = &collector.recordings()[0];
assert_eq!(
recording.error.as_deref(),
Some("save cast: disk on fire"),
"the failure has to name the step"
);
assert_eq!(recording.video, None);
assert_eq!(recording.url, None);
assert!(
uploaded.lock().expect("poisoned").is_empty(),
"nothing to upload, so nothing was uploaded"
);
assert!(!Path::new(&recording.cast).exists());
}
#[test]
fn a_save_that_writes_nothing_is_the_save_step_failing() {
let dir = tempfile::tempdir().expect("tempdir");
let mut publisher = publisher(dir.path()).with_video_converter(stub_converter());
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, |_| Ok(()));
let error = collector.recordings()[0].error.clone().expect("error");
assert!(error.starts_with("save cast: "), "{error}");
assert!(error.contains("wrote no file"), "{error}");
assert_eq!(collector.recordings()[0].video, None);
}
#[test]
fn an_append_failure_does_not_stop_the_conversion() {
let dir = tempfile::tempdir().expect("tempdir");
let mut publisher = publisher(dir.path()).with_video_converter(stub_converter());
let mut collector = one_capture();
collector.record_session("empty", &mut publisher, |dest| {
std::fs::write(dest, "").map_err(|e| e.to_string())
});
let error = collector.recordings()[0].error.clone().expect("error");
assert_eq!(
error,
"append checkpoint frames: empty cast file; convert: empty cast file"
);
}
#[test]
fn a_publisher_with_no_video_converter_says_so() {
let dir = tempfile::tempdir().expect("tempdir");
let mut publisher = publisher(dir.path());
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, save_a_cast);
let recording = &collector.recordings()[0];
assert_eq!(
recording.error.as_deref(),
Some("convert: no video converter configured")
);
assert!(Path::new(&recording.cast).exists());
assert!(std::fs::read_to_string(&recording.cast)
.expect("cast")
.contains("screen text"));
assert_eq!(recording.video, None);
}
#[test]
fn a_failed_conversion_is_never_uploaded() {
let dir = tempfile::tempdir().expect("tempdir");
let uploaded = Arc::new(Mutex::new(Vec::new()));
let mut publisher = publisher(dir.path())
.with_video_converter(broken_converter())
.with_uploader(Box::new(CountingUploader(uploaded.clone())));
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, save_a_cast);
let recording = &collector.recordings()[0];
assert_eq!(
recording.error.as_deref(),
Some("convert: encoder exploded")
);
assert_eq!(recording.video, None);
assert_eq!(recording.url, None);
assert!(
uploaded.lock().expect("poisoned").is_empty(),
"an upload was attempted for a video that does not exist"
);
}
#[test]
fn a_converter_that_writes_nothing_is_the_convert_step_failing() {
let dir = tempfile::tempdir().expect("tempdir");
let uploaded = Arc::new(Mutex::new(Vec::new()));
let mut publisher = publisher(dir.path())
.with_video_converter(silent_converter())
.with_uploader(Box::new(CountingUploader(uploaded.clone())));
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, save_a_cast);
let recording = &collector.recordings()[0];
let error = recording.error.clone().expect("error");
assert!(error.starts_with("convert: "), "{error}");
assert!(error.contains("wrote no file"), "{error}");
assert_eq!(recording.video, None, "a video that is not on disk");
assert_eq!(recording.url, None);
assert!(
uploaded.lock().expect("poisoned").is_empty(),
"a video that was never written must not be uploaded"
);
}
#[test]
fn an_empty_url_is_no_url() {
struct Blank;
impl ArtifactUploader for Blank {
fn upload(&mut self, _: &str) -> Option<String> {
Some(String::new())
}
fn last_error(&self) -> Option<&str> {
None
}
}
let dir = tempfile::tempdir().expect("tempdir");
let mut publisher = publisher(dir.path())
.with_video_converter(stub_converter())
.with_uploader(Box::new(Blank));
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, save_a_cast);
let recording = &collector.recordings()[0];
assert_eq!(
recording.error.as_deref(),
Some("upload: uploader returned no URL")
);
assert_eq!(recording.url, None);
assert!(recording.video.is_some());
}
#[test]
fn a_failed_upload_keeps_the_video() {
struct Refuses;
impl ArtifactUploader for Refuses {
fn upload(&mut self, _: &str) -> Option<String> {
None
}
fn last_error(&self) -> Option<&str> {
Some("store down")
}
}
let dir = tempfile::tempdir().expect("tempdir");
let mut publisher = publisher(dir.path())
.with_video_converter(stub_converter())
.with_uploader(Box::new(Refuses));
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, save_a_cast);
let recording = &collector.recordings()[0];
assert_eq!(recording.error.as_deref(), Some("upload: store down"));
assert!(recording.video.is_some());
assert_eq!(recording.url, None);
}
#[test]
fn an_uploader_that_declines_without_a_reason_still_names_the_step() {
struct Silent;
impl ArtifactUploader for Silent {
fn upload(&mut self, _: &str) -> Option<String> {
None
}
fn last_error(&self) -> Option<&str> {
None
}
}
let dir = tempfile::tempdir().expect("tempdir");
let mut publisher = publisher(dir.path())
.with_video_converter(stub_converter())
.with_uploader(Box::new(Silent));
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, save_a_cast);
assert_eq!(
collector.recordings()[0].error.as_deref(),
Some("upload: uploader returned no URL")
);
}
#[test]
fn a_publisher_with_no_uploader_is_not_a_failure() {
let dir = tempfile::tempdir().expect("tempdir");
let mut publisher = publisher(dir.path()).with_video_converter(stub_converter());
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, save_a_cast);
let recording = &collector.recordings()[0];
assert_eq!(recording.error, None);
assert!(recording.video.is_some());
assert_eq!(recording.url, None);
}
#[test]
fn two_recordings_with_one_label_do_not_share_a_cast() {
let dir = tempfile::tempdir().expect("tempdir");
let mut publisher = publisher(dir.path()).with_video_converter(stub_converter());
let mut collector = one_capture();
collector.record_session("full-session", &mut publisher, save_a_cast);
collector.record_session("full-session", &mut publisher, save_a_cast);
let recordings = collector.recordings();
assert_ne!(recordings[0].cast, recordings[1].cast);
assert_ne!(recordings[0].video, recordings[1].video);
assert!(recordings[1]
.cast
.ends_with("recording-01-full-session.cast"));
assert!(recordings.iter().all(|r| r.error.is_none()));
}
#[test]
fn an_empty_label_names_a_recording_the_way_python_names_it() {
assert_eq!(recording_file_stem(0, ""), "recording-00-default");
assert_eq!(recording_file_stem(1, "!!"), "recording-01---");
}
#[test]
fn a_recorded_session_sits_beside_a_hand_attached_one() {
let dir = tempfile::tempdir().expect("tempdir");
let mut publisher = publisher(dir.path()).with_video_converter(stub_converter());
let mut collector = one_capture();
collector.attach_recording(Recording::new("hand-made", "/tmp/other.cast"));
collector.record_session("full-session", &mut publisher, save_a_cast);
let manifest = collector.publish(&mut publisher).expect("published");
let labels: Vec<&str> = manifest
.recordings
.iter()
.map(|r| r.label.as_str())
.collect();
assert_eq!(labels, ["hand-made", "full-session"]);
}
#[test]
fn captures_keep_their_order_and_labels() {
let mut s = session("a");
let mut collector = EvidenceCollector::new();
collector.capture("first", &mut s);
s.set_screen("b");
collector.capture_failure("blew-up", &mut s);
assert_eq!(collector.steps()[0].index, 0);
assert_eq!(collector.steps()[1].index, 1);
assert_eq!(collector.steps()[1].label, "blew-up");
assert_eq!(collector.steps()[1].kind, CaptureKind::Failure);
}
#[test]
fn raw_output_is_kept_for_failures_only() {
let mut s = session("screen");
s.set_raw("all of it");
let mut collector = EvidenceCollector::new();
collector.capture("fine", &mut s);
collector.capture_failure("broken", &mut s);
assert_eq!(collector.steps()[0].raw_output, None);
assert_eq!(
collector.steps()[1].raw_output.as_deref(),
Some("all of it")
);
}
#[test]
fn a_text_only_source_still_gets_a_grid() {
let mut replay = Replay {
frames: vec!["hello".into()],
at: 0,
};
let mut collector = EvidenceCollector::with_grid(20, 2);
collector.capture("only-text", &mut replay);
assert_eq!(collector.steps()[0].attributed.to_text(true), "hello");
}
#[test]
fn publish_writes_text_for_every_step() {
let dir = tempfile::tempdir().expect("tempdir");
let mut s = session("first screen");
let mut collector = EvidenceCollector::new();
collector.capture("start", &mut s);
s.set_screen("second screen");
collector.capture("end", &mut s);
let manifest = collector
.publish(&mut publisher(dir.path()))
.expect("published");
for step in &manifest.steps {
assert!(Path::new(&step.screen_text).exists(), "{:?}", step);
}
assert_eq!(
std::fs::read_to_string(&manifest.steps[0].screen_text).expect("read"),
"first screen"
);
}
#[test]
fn a_deduped_step_still_gets_its_own_text() {
let dir = tempfile::tempdir().expect("tempdir");
let mut s = session("unchanged");
let mut collector = EvidenceCollector::new();
collector.capture("before", &mut s);
collector.capture("after", &mut s);
let (mut publisher, rendered) = counting_publisher(dir.path());
let manifest = collector.publish(&mut publisher).expect("published");
assert_eq!(rendered.lock().expect("poisoned").len(), 1);
assert_eq!(
manifest.steps[1].same_as,
Some(ReusedFrom {
index: 0,
label: "before".to_string()
})
);
assert_eq!(manifest.steps[0].screenshot, manifest.steps[1].screenshot);
assert_ne!(manifest.steps[0].screen_text, manifest.steps[1].screen_text);
assert!(Path::new(&manifest.steps[1].screen_text).exists());
}
#[test]
fn a_reused_image_names_which_step_owns_it_even_when_labels_repeat() {
let dir = tempfile::tempdir().expect("tempdir");
let mut s = session("one");
let mut collector = EvidenceCollector::new();
collector.capture("check", &mut s);
s.set_screen("two");
collector.capture("other", &mut s);
s.set_screen("three");
collector.capture("check", &mut s);
collector.capture("after", &mut s);
let manifest = collector
.publish(&mut publisher(dir.path()))
.expect("published");
let reused = manifest.steps[3].same_as.as_ref().expect("reused");
assert_eq!(reused.label, "check");
assert_eq!(reused.index, 2);
assert_eq!(
manifest.steps[3].screenshot, manifest.steps[2].screenshot,
"the index must name the step that actually owns the image"
);
}
#[test]
fn dedup_only_looks_back_one_step() {
let dir = tempfile::tempdir().expect("tempdir");
let mut s = session("one");
let mut collector = EvidenceCollector::new();
collector.capture("a", &mut s);
s.set_screen("two");
collector.capture("b", &mut s);
s.set_screen("one");
collector.capture("c", &mut s);
let manifest = collector
.publish(&mut publisher(dir.path()))
.expect("published");
assert_eq!(manifest.deduped().count(), 0);
assert_eq!(manifest.steps[2].same_as, None);
}
#[test]
fn same_text_different_colour_is_not_deduped() {
let dir = tempfile::tempdir().expect("tempdir");
struct Coloured(&'static str);
impl ScreenSource for Coloured {
fn capture_screen(&mut self, _: RawOutput) -> ScreenCapture {
ScreenCapture {
screen: "hi".to_string(),
attributed: Some(attributed_screen_from_ansi_text(self.0, 20, 2)),
raw_output: None,
}
}
}
let mut collector = EvidenceCollector::new();
collector.capture("red", &mut Coloured("\x1b[31mhi"));
collector.capture("green", &mut Coloured("\x1b[32mhi"));
let manifest = collector
.publish(&mut publisher(dir.path()))
.expect("published");
assert_eq!(manifest.steps[1].same_as, None);
}
#[test]
fn a_failed_render_does_not_make_the_next_identical_screen_reuse_it() {
let dir = tempfile::tempdir().expect("tempdir");
let attempts = Arc::new(Mutex::new(0usize));
let sink = attempts.clone();
let mut publisher = EvidencePublisher::new(dir.path(), identity()).with_renderer(
ScreenshotRenderer::with_runner(Box::new(move |_, _, _| {
*sink.lock().expect("poisoned") += 1;
Err("rsvg-convert missing".to_string())
})),
);
let mut s = session("unchanged");
let mut collector = EvidenceCollector::new();
collector.capture("before", &mut s);
collector.capture("after", &mut s);
let manifest = collector.publish(&mut publisher).expect("published");
assert_eq!(*attempts.lock().expect("poisoned"), 2);
assert_eq!(manifest.steps[1].same_as, None);
assert!(manifest.steps.iter().all(|s| s.screenshot.is_none()));
assert!(manifest.steps[0]
.error
.as_deref()
.expect("error")
.contains("rsvg-convert"));
assert!(Path::new(&manifest.steps[0].screen_text).exists());
}
#[test]
fn uploads_are_best_effort() {
struct Nope;
impl ArtifactUploader for Nope {
fn upload(&mut self, _: &str) -> Option<String> {
None
}
fn last_error(&self) -> Option<&str> {
Some("store down")
}
}
let dir = tempfile::tempdir().expect("tempdir");
let mut p = publisher(dir.path()).with_uploader(Box::new(Nope));
let mut collector = EvidenceCollector::new();
collector.capture("only", &mut session("x"));
let manifest = collector.publish(&mut p).expect("published");
assert_eq!(manifest.steps[0].url, None);
assert!(manifest.steps[0].screenshot.is_some());
}
#[test]
fn a_deduped_step_reuses_the_url_as_well_as_the_image() {
struct Counting(usize);
impl ArtifactUploader for Counting {
fn upload(&mut self, _: &str) -> Option<String> {
self.0 += 1;
Some(format!("https://example/{}", self.0))
}
fn last_error(&self) -> Option<&str> {
None
}
}
let dir = tempfile::tempdir().expect("tempdir");
let mut p = publisher(dir.path()).with_uploader(Box::new(Counting(0)));
let mut s = session("same");
let mut collector = EvidenceCollector::new();
collector.capture("before", &mut s);
collector.capture("after", &mut s);
let manifest = collector.publish(&mut p).expect("published");
assert_eq!(manifest.steps[0].url.as_deref(), Some("https://example/1"));
assert_eq!(manifest.steps[1].url, manifest.steps[0].url);
}
#[test]
fn the_manifest_is_written_and_reads_back() {
let dir = tempfile::tempdir().expect("tempdir");
let mut collector = EvidenceCollector::new();
collector.capture("only", &mut session("x"));
let manifest = collector
.publish(&mut publisher(dir.path()))
.expect("published");
let written = std::fs::read_to_string(dir.path().join(MANIFEST_FILE)).expect("read");
let parsed: EvidenceManifest = serde_json::from_str(&written).expect("parse");
assert_eq!(parsed.manifest_version, EVIDENCE_MANIFEST_VERSION);
assert_eq!(parsed.run, identity());
assert_eq!(parsed.steps, manifest.steps);
assert!(!written.contains(MANIFEST_FILE));
}
#[test]
fn attaching_to_the_matching_run_records_the_manifest() {
let dir = tempfile::tempdir().expect("tempdir");
let mut collector = EvidenceCollector::new();
collector.capture("only", &mut session("x"));
let manifest = collector
.publish(&mut publisher(dir.path()))
.expect("published");
let mut result = run_result("login", "default");
manifest.attach_to(&mut result).expect("attached");
assert_eq!(
result
.artifacts
.get("evidence_manifest")
.map(String::as_str),
Some(path_string(&dir.path().join(MANIFEST_FILE)).as_str())
);
}
#[test]
fn evidence_from_another_run_is_refused() {
let dir = tempfile::tempdir().expect("tempdir");
let mut collector = EvidenceCollector::new();
collector.capture("only", &mut session("x"));
let manifest = collector
.publish(&mut publisher(dir.path()))
.expect("published");
let mut other = run_result("checkout", "default");
let error = manifest.attach_to(&mut other).expect_err("refused");
assert!(error.contains("login"), "{error}");
assert!(error.contains("checkout"), "{error}");
assert!(other.artifacts.is_empty());
let mut other_renderer = run_result("login", "tmux");
assert!(manifest.attach_to(&mut other_renderer).is_err());
}
#[test]
fn a_run_id_comes_from_the_run_directory() {
let base = Path::new("/tmp/out");
let first = crate::store::new_run_dir(base, "login", "default");
let identity = RunIdentity::from_run_dir(&first, "login", "default");
assert_eq!(
identity.run_id,
first.file_name().expect("name").to_string_lossy()
);
assert!(identity.run_id.contains("login"));
assert!(identity.matches(&run_result("login", "default")));
}
#[test]
fn filenames_are_ordered_and_sanitized() {
let step = CapturedStep {
index: 7,
label: "menu/open: 100%".to_string(),
kind: CaptureKind::Checkpoint,
screen: String::new(),
attributed: AttributedScreen::default(),
raw_output: None,
};
assert_eq!(step.file_stem(), "step-07-menu-open--100-");
}
#[test]
fn a_long_label_does_not_produce_a_long_filename() {
let step = CapturedStep {
index: 0,
label: "x".repeat(200),
kind: CaptureKind::Checkpoint,
screen: String::new(),
attributed: AttributedScreen::default(),
raw_output: None,
};
assert_eq!(step.file_stem().len(), "step-00-".len() + 40);
}
#[test]
fn publishing_twice_is_allowed() {
let dir = tempfile::tempdir().expect("tempdir");
let other = tempfile::tempdir().expect("tempdir");
let mut collector = EvidenceCollector::new();
collector.capture("only", &mut session("x"));
let first = collector
.publish(&mut publisher(dir.path()))
.expect("published");
let second = collector
.publish(&mut publisher(other.path()))
.expect("published");
assert_ne!(first.path(), second.path());
assert_eq!(first.steps.len(), second.steps.len());
}
#[test]
fn publishing_nothing_still_writes_a_manifest() {
let dir = tempfile::tempdir().expect("tempdir");
let manifest = EvidenceCollector::new()
.publish(&mut publisher(dir.path()))
.expect("published");
assert!(manifest.steps.is_empty());
assert!(dir.path().join(MANIFEST_FILE).exists());
}
}