1#![forbid(unsafe_code)]
2
3use crate::terminal_model::TerminalModel;
32use std::fmt;
33use std::io;
34use std::path::Path;
35
36#[derive(Debug)]
41pub struct HeadlessTerm {
42 model: TerminalModel,
43 captured_output: Vec<u8>,
44}
45
46impl HeadlessTerm {
47 pub fn new(width: u16, height: u16) -> Self {
53 assert!(width > 0, "width must be > 0");
54 assert!(height > 0, "height must be > 0");
55 Self {
56 model: TerminalModel::new(width as usize, height as usize),
57 captured_output: Vec::new(),
58 }
59 }
60
61 pub fn width(&self) -> u16 {
63 self.model.width() as u16
64 }
65
66 pub fn height(&self) -> u16 {
68 self.model.height() as u16
69 }
70
71 pub fn cursor(&self) -> (u16, u16) {
73 let (x, y) = self.model.cursor();
74 (x as u16, y as u16)
75 }
76
77 pub fn process(&mut self, bytes: &[u8]) {
82 self.captured_output.extend_from_slice(bytes);
83 self.model.process(bytes);
84 }
85
86 pub fn row_text(&self, row: usize) -> String {
90 self.model.row_text(row).unwrap_or_default()
91 }
92
93 pub fn screen_text(&self) -> Vec<String> {
95 (0..self.model.height())
96 .map(|y| self.model.row_text(y).unwrap_or_default())
97 .collect()
98 }
99
100 pub fn screen_string(&self) -> String {
102 self.screen_text().join("\n")
103 }
104
105 #[must_use]
107 pub fn model(&self) -> &TerminalModel {
108 &self.model
109 }
110
111 #[must_use]
113 pub fn captured_output(&self) -> &[u8] {
114 &self.captured_output
115 }
116
117 pub fn reset(&mut self) {
119 self.model.reset();
120 self.captured_output.clear();
121 }
122
123 pub fn assert_matches(&self, expected: &[&str]) {
134 let actual = self.screen_text();
135
136 assert_eq!(
137 actual.len(),
138 expected.len(),
139 "HeadlessTerm: line count mismatch: got {} lines, expected {} lines\n\
140 Hint: expected slice length must equal terminal height ({})",
141 actual.len(),
142 expected.len(),
143 self.height(),
144 );
145
146 let mismatches: Vec<LineDiff> = actual
147 .iter()
148 .zip(expected.iter())
149 .enumerate()
150 .filter_map(|(i, (got, want))| {
151 let want_trimmed = want.trim_end();
152 if got.as_str() != want_trimmed {
153 Some(LineDiff {
154 line: i,
155 got: got.clone(),
156 want: want_trimmed.to_string(),
157 })
158 } else {
159 None
160 }
161 })
162 .collect();
163
164 assert!(
165 mismatches.is_empty(),
166 "HeadlessTerm: screen content mismatch\n{}",
167 format_diff(&mismatches)
168 );
169 }
170
171 pub fn assert_row(&self, row: usize, expected: &str) {
179 let actual = self.row_text(row);
180 let expected_trimmed = expected.trim_end();
181 assert_eq!(
182 actual, expected_trimmed,
183 "HeadlessTerm: row {row} mismatch\n got: {actual:?}\n want: {expected_trimmed:?}",
184 );
185 }
186
187 pub fn assert_cursor(&self, col: u16, row: u16) {
193 let (actual_col, actual_row) = self.cursor();
194 assert_eq!(
195 (actual_col, actual_row),
196 (col, row),
197 "HeadlessTerm: cursor position mismatch\n got: ({actual_col}, {actual_row})\n want: ({col}, {row})",
198 );
199 }
200
201 pub fn diff(&self, expected: &[&str]) -> Option<ScreenDiff> {
205 let actual = self.screen_text();
206 let mismatches: Vec<LineDiff> = actual
207 .iter()
208 .zip(expected.iter())
209 .enumerate()
210 .filter_map(|(i, (got, want))| {
211 let want_trimmed = want.trim_end();
212 if got.as_str() != want_trimmed {
213 Some(LineDiff {
214 line: i,
215 got: got.clone(),
216 want: want_trimmed.to_string(),
217 })
218 } else {
219 None
220 }
221 })
222 .collect();
223
224 let line_count_mismatch = actual.len() != expected.len();
225
226 if mismatches.is_empty() && !line_count_mismatch {
227 None
228 } else {
229 Some(ScreenDiff {
230 actual_lines: actual.len(),
231 expected_lines: expected.len(),
232 mismatches,
233 })
234 }
235 }
236
237 pub fn export(&self, path: &Path) -> io::Result<()> {
247 use std::io::Write;
248 let mut file = std::fs::File::create(path)?;
249
250 writeln!(file, "=== HeadlessTerm Export ===")?;
251 writeln!(file, "Size: {}x{}", self.width(), self.height())?;
252 let (cx, cy) = self.cursor();
253 writeln!(file, "Cursor: ({cx}, {cy})")?;
254 writeln!(
255 file,
256 "Captured output: {} bytes",
257 self.captured_output.len()
258 )?;
259 writeln!(file)?;
260 writeln!(file, "--- Screen Content ---")?;
261
262 for y in 0..self.model.height() {
263 let text = self.row_text(y);
264 writeln!(file, "{y:3}| {text}")?;
265 }
266
267 writeln!(file)?;
268 writeln!(file, "--- ANSI Dump ---")?;
269 writeln!(
270 file,
271 "{}",
272 TerminalModel::dump_sequences(&self.captured_output)
273 )?;
274
275 Ok(())
276 }
277
278 pub fn export_string(&self) -> String {
280 let mut out = String::new();
281 out.push_str(&format!("{}x{}", self.width(), self.height()));
282 let (cx, cy) = self.cursor();
283 out.push_str(&format!(" cursor=({cx},{cy})\n"));
284
285 for y in 0..self.model.height() {
286 let text = self.row_text(y);
287 out.push_str(&format!("{y:3}| {text}\n"));
288 }
289 out
290 }
291}
292
293#[derive(Debug, Clone)]
295pub struct LineDiff {
296 pub line: usize,
298 pub got: String,
300 pub want: String,
302}
303
304#[derive(Debug, Clone)]
306pub struct ScreenDiff {
307 pub actual_lines: usize,
309 pub expected_lines: usize,
311 pub mismatches: Vec<LineDiff>,
313}
314
315impl fmt::Display for ScreenDiff {
316 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
317 if self.actual_lines != self.expected_lines {
318 writeln!(
319 f,
320 "Line count: got {}, expected {}",
321 self.actual_lines, self.expected_lines,
322 )?;
323 }
324 write!(f, "{}", format_diff(&self.mismatches))
325 }
326}
327
328fn format_diff(mismatches: &[LineDiff]) -> String {
329 let mut out = String::new();
330 for d in mismatches {
331 out.push_str(&format!(" line {}:\n", d.line));
332 out.push_str(&format!(" got: {:?}\n", d.got));
333 out.push_str(&format!(" want: {:?}\n", d.want));
334
335 let diff_col = d.got.chars().zip(d.want.chars()).position(|(a, b)| a != b);
337 if let Some(col) = diff_col {
338 out.push_str(&format!(" first difference at column {col}\n"));
339 } else if d.got.len() != d.want.len() {
340 let shorter = d.got.len().min(d.want.len());
341 out.push_str(&format!(
342 " diverges at column {shorter} (length difference)\n"
343 ));
344 }
345 }
346 out
347}
348
349#[cfg(test)]
350mod tests {
351 use super::*;
352
353 #[test]
354 fn new_creates_blank_screen() {
355 let term = HeadlessTerm::new(80, 24);
356 assert_eq!(term.width(), 80);
357 assert_eq!(term.height(), 24);
358 assert_eq!(term.cursor(), (0, 0));
359
360 let text = term.screen_text();
361 assert_eq!(text.len(), 24);
362 assert!(text.iter().all(|line| line.is_empty()));
363 }
364
365 #[test]
366 fn process_writes_text() {
367 let mut term = HeadlessTerm::new(20, 5);
368 term.process(b"Hello, world!");
369 assert_eq!(term.row_text(0), "Hello, world!");
370 assert_eq!(term.cursor(), (13, 0));
371 }
372
373 #[test]
374 fn process_cup_and_text() {
375 let mut term = HeadlessTerm::new(20, 5);
376 term.process(b"\x1b[2;3HTest"); assert_eq!(term.row_text(1), " Test");
378 assert_eq!(term.cursor(), (6, 1));
379 }
380
381 #[test]
382 fn screen_text_returns_all_rows() {
383 let mut term = HeadlessTerm::new(10, 3);
384 term.process(b"\x1b[1;1HLine 1");
385 term.process(b"\x1b[2;1HLine 2");
386 term.process(b"\x1b[3;1HLine 3");
387
388 let text = term.screen_text();
389 assert_eq!(text, vec!["Line 1", "Line 2", "Line 3"]);
390 }
391
392 #[test]
393 fn screen_string_joins_with_newlines() {
394 let mut term = HeadlessTerm::new(10, 3);
395 term.process(b"\x1b[1;1HAB");
396 term.process(b"\x1b[2;1HCD");
397
398 assert_eq!(term.screen_string(), "AB\nCD\n");
399 }
400
401 #[test]
402 fn assert_matches_passes_on_match() {
403 let mut term = HeadlessTerm::new(10, 3);
404 term.process(b"\x1b[1;1HHello");
405 term.process(b"\x1b[3;1HWorld");
406
407 term.assert_matches(&["Hello", "", "World"]);
408 }
409
410 #[test]
411 #[should_panic(expected = "screen content mismatch")]
412 fn assert_matches_panics_on_mismatch() {
413 let mut term = HeadlessTerm::new(10, 3);
414 term.process(b"Hello");
415
416 term.assert_matches(&["Wrong", "", ""]);
417 }
418
419 #[test]
420 #[should_panic(expected = "line count mismatch")]
421 fn assert_matches_panics_on_wrong_line_count() {
422 let term = HeadlessTerm::new(10, 3);
423 term.assert_matches(&["", ""]); }
425
426 #[test]
427 fn assert_row_passes_on_match() {
428 let mut term = HeadlessTerm::new(10, 3);
429 term.process(b"Hello");
430 term.assert_row(0, "Hello");
431 }
432
433 #[test]
434 #[should_panic(expected = "row 0 mismatch")]
435 fn assert_row_panics_on_mismatch() {
436 let mut term = HeadlessTerm::new(10, 3);
437 term.process(b"Hello");
438 term.assert_row(0, "World");
439 }
440
441 #[test]
442 fn assert_cursor_passes_on_match() {
443 let mut term = HeadlessTerm::new(20, 5);
444 term.process(b"\x1b[3;5H");
445 term.assert_cursor(4, 2); }
447
448 #[test]
449 #[should_panic(expected = "cursor position mismatch")]
450 fn assert_cursor_panics_on_mismatch() {
451 let term = HeadlessTerm::new(20, 5);
452 term.assert_cursor(5, 5);
453 }
454
455 #[test]
456 fn diff_returns_none_on_match() {
457 let mut term = HeadlessTerm::new(10, 2);
458 term.process(b"AB");
459 assert!(term.diff(&["AB", ""]).is_none());
460 }
461
462 #[test]
463 fn diff_returns_mismatches() {
464 let mut term = HeadlessTerm::new(10, 3);
465 term.process(b"\x1b[1;1HHello");
466 term.process(b"\x1b[3;1HWorld");
467
468 let diff = term.diff(&["Hello", "X", "World"]).unwrap();
469 assert_eq!(diff.mismatches.len(), 1);
470 assert_eq!(diff.mismatches[0].line, 1);
471 assert_eq!(diff.mismatches[0].got, "");
472 assert_eq!(diff.mismatches[0].want, "X");
473 }
474
475 #[test]
476 fn diff_detects_character_difference() {
477 let mut term = HeadlessTerm::new(10, 1);
478 term.process(b"ABCXEF");
479
480 let diff = term.diff(&["ABCDEF"]).unwrap();
481 assert_eq!(diff.mismatches[0].line, 0);
482 }
483
484 #[test]
485 fn reset_clears_everything() {
486 let mut term = HeadlessTerm::new(10, 3);
487 term.process(b"Hello");
488 term.reset();
489
490 assert_eq!(term.cursor(), (0, 0));
491 assert!(term.captured_output().is_empty());
492 assert!(term.screen_text().iter().all(|l| l.is_empty()));
493 }
494
495 #[test]
496 fn captured_output_records_all_bytes() {
497 let mut term = HeadlessTerm::new(10, 3);
498 term.process(b"\x1b[1mHello");
499 term.process(b"\x1b[0m");
500
501 assert_eq!(term.captured_output(), b"\x1b[1mHello\x1b[0m");
502 }
503
504 #[test]
505 fn export_string_contains_dimensions_and_content() {
506 let mut term = HeadlessTerm::new(10, 3);
507 term.process(b"Test");
508
509 let export = term.export_string();
510 assert!(export.contains("10x3"));
511 assert!(export.contains("Test"));
512 }
513
514 #[test]
515 fn export_to_file() {
516 use std::time::{SystemTime, UNIX_EPOCH};
517 let timestamp = SystemTime::now()
520 .duration_since(UNIX_EPOCH)
521 .map(|d| d.as_nanos())
522 .unwrap_or(0);
523 let thread_id = format!("{:?}", std::thread::current().id());
524 let dir = std::env::temp_dir().join(format!("ftui_headless_test_{timestamp}_{thread_id}"));
525 std::fs::create_dir_all(&dir).unwrap();
526 let path = dir.join("export_test.txt");
527
528 let mut term = HeadlessTerm::new(20, 5);
529 term.process(b"\x1b[1;1HExported content");
530 term.export(&path).unwrap();
531
532 let contents = std::fs::read_to_string(&path).unwrap();
533 assert!(contents.contains("HeadlessTerm Export"));
534 assert!(contents.contains("20x5"));
535 assert!(contents.contains("Exported content"));
536 assert!(contents.contains("ANSI Dump"));
537
538 }
540
541 #[test]
542 fn sgr_styling_tracked() {
543 let mut term = HeadlessTerm::new(20, 5);
544 term.process(b"\x1b[1;31mBold Red\x1b[0m");
545
546 assert_eq!(term.row_text(0), "Bold Red");
548
549 let cell = term.model().cell(0, 0).unwrap();
551 assert!(cell.attrs.has_flag(crate::cell::StyleFlags::BOLD));
552 }
553
554 #[test]
555 fn multiline_content() {
556 let mut term = HeadlessTerm::new(20, 5);
557 term.process(b"Line 1\r\nLine 2\r\nLine 3");
558
559 term.assert_matches(&["Line 1", "Line 2", "Line 3", "", ""]);
560 }
561
562 #[test]
563 fn erase_operations_work() {
564 let mut term = HeadlessTerm::new(10, 3);
565 term.process(b"XXXXXXXXXX");
566 term.process(b"\x1b[1;1H"); term.process(b"\x1b[2J"); term.assert_matches(&["", "", ""]);
570 }
571
572 #[test]
573 fn line_wrap_at_boundary() {
574 let mut term = HeadlessTerm::new(5, 3);
575 term.process(b"ABCDEFGH");
576
577 assert_eq!(term.row_text(0), "ABCDE");
578 assert_eq!(term.row_text(1), "FGH");
579 }
580
581 #[test]
582 fn hyperlink_tracking() {
583 let mut term = HeadlessTerm::new(20, 5);
584 term.process(b"\x1b]8;;https://example.com\x07Link\x1b]8;;\x07");
585
586 assert_eq!(term.row_text(0), "Link");
587 assert!(!term.model().has_dangling_link());
588 }
589
590 #[test]
591 fn screen_diff_display_format() {
592 let diff = ScreenDiff {
593 actual_lines: 3,
594 expected_lines: 3,
595 mismatches: vec![LineDiff {
596 line: 1,
597 got: "actual".to_string(),
598 want: "expected".to_string(),
599 }],
600 };
601
602 let display = format!("{diff}");
603 assert!(display.contains("line 1"));
604 assert!(display.contains("actual"));
605 assert!(display.contains("expected"));
606 }
607
608 #[test]
609 fn format_diff_shows_column_of_first_difference() {
610 let diffs = vec![LineDiff {
611 line: 0,
612 got: "ABCXEF".to_string(),
613 want: "ABCDEF".to_string(),
614 }];
615
616 let formatted = format_diff(&diffs);
617 assert!(formatted.contains("first difference at column 3"));
618 }
619
620 #[test]
621 fn format_diff_shows_length_difference() {
622 let diffs = vec![LineDiff {
623 line: 0,
624 got: "ABC".to_string(),
625 want: "ABCDEF".to_string(),
626 }];
627
628 let formatted = format_diff(&diffs);
629 assert!(formatted.contains("diverges at column 3"));
630 }
631
632 #[test]
635 fn presenter_output_roundtrips() {
636 use crate::buffer::Buffer;
637 use crate::cell::Cell;
638 use crate::diff::BufferDiff;
639 use crate::presenter::{Presenter, TerminalCapabilities};
640
641 let prev = Buffer::new(10, 3);
643 let mut next = Buffer::new(10, 3);
644
645 for (i, ch) in "Hello".chars().enumerate() {
647 next.set(i as u16, 0, Cell::from_char(ch));
648 }
649
650 let diff = BufferDiff::compute(&prev, &next);
652
653 let output = {
655 let mut buf = Vec::new();
656 let caps = TerminalCapabilities::default();
657 let mut presenter = Presenter::new(&mut buf, caps);
658 presenter.present(&next, &diff).unwrap();
659 drop(presenter); buf
661 };
662
663 let mut term = HeadlessTerm::new(10, 3);
665 term.process(&output);
666
667 term.assert_row(0, "Hello");
669 }
670
671 #[test]
672 fn presenter_incremental_update_roundtrips() {
673 use crate::buffer::Buffer;
674 use crate::cell::Cell;
675 use crate::diff::BufferDiff;
676 use crate::presenter::{Presenter, TerminalCapabilities};
677
678 let mut term = HeadlessTerm::new(10, 3);
679
680 let prev = Buffer::new(10, 3);
682 let mut next = Buffer::new(10, 3);
683 for (i, ch) in "Hello".chars().enumerate() {
684 next.set(i as u16, 0, Cell::from_char(ch));
685 }
686
687 let diff = BufferDiff::compute(&prev, &next);
688 let output = {
689 let mut buf = Vec::new();
690 let caps = TerminalCapabilities::default();
691 let mut presenter = Presenter::new(&mut buf, caps);
692 presenter.present(&next, &diff).unwrap();
693 drop(presenter);
694 buf
695 };
696 term.process(&output);
697 term.assert_row(0, "Hello");
698
699 let prev2 = next;
701 let mut next2 = Buffer::new(10, 3);
702 for (i, ch) in "World".chars().enumerate() {
703 next2.set(i as u16, 0, Cell::from_char(ch));
704 }
705
706 let diff2 = BufferDiff::compute(&prev2, &next2);
707 let output2 = {
708 let mut buf = Vec::new();
709 let caps = TerminalCapabilities::default();
710 let mut presenter = Presenter::new(&mut buf, caps);
711 presenter.present(&next2, &diff2).unwrap();
712 drop(presenter);
713 buf
714 };
715 term.process(&output2);
716 term.assert_row(0, "World");
717 }
718
719 #[test]
722 fn cursor_move_up() {
723 let mut term = HeadlessTerm::new(20, 10);
724 term.process(b"\x1b[5;5H"); term.assert_cursor(4, 4);
726 term.process(b"\x1b[2A"); term.assert_cursor(4, 2);
728 }
729
730 #[test]
731 fn cursor_move_down() {
732 let mut term = HeadlessTerm::new(20, 10);
733 term.process(b"\x1b[1;1H"); term.assert_cursor(0, 0);
735 term.process(b"\x1b[3B"); term.assert_cursor(0, 3);
737 }
738
739 #[test]
740 fn cursor_move_forward() {
741 let mut term = HeadlessTerm::new(20, 10);
742 term.process(b"\x1b[1;1H"); term.assert_cursor(0, 0);
744 term.process(b"\x1b[5C"); term.assert_cursor(5, 0);
746 }
747
748 #[test]
749 fn cursor_move_back() {
750 let mut term = HeadlessTerm::new(20, 10);
751 term.process(b"\x1b[1;10H"); term.assert_cursor(9, 0);
753 term.process(b"\x1b[4D"); term.assert_cursor(5, 0);
755 }
756
757 #[test]
758 fn cursor_move_default_count() {
759 let mut term = HeadlessTerm::new(20, 10);
761 term.process(b"\x1b[5;5H"); term.process(b"\x1b[A"); term.assert_cursor(4, 3);
764 term.process(b"\x1b[C"); term.assert_cursor(5, 3);
766 term.process(b"\x1b[B"); term.assert_cursor(5, 4);
768 term.process(b"\x1b[D"); term.assert_cursor(4, 4);
770 }
771
772 #[test]
773 fn cursor_multiple_directions() {
774 let mut term = HeadlessTerm::new(20, 10);
775 term.process(b"\x1b[1;1H"); term.process(b"\x1b[3C"); term.process(b"\x1b[2B"); term.process(b"\x1b[1D"); term.process(b"\x1b[1A"); term.assert_cursor(2, 1);
781 }
782
783 #[test]
784 fn cursor_clamped_at_top() {
785 let mut term = HeadlessTerm::new(20, 10);
786 term.process(b"\x1b[1;1H"); term.process(b"\x1b[99A"); term.assert_cursor(0, 0); }
790
791 #[test]
792 fn cursor_clamped_at_left() {
793 let mut term = HeadlessTerm::new(20, 10);
794 term.process(b"\x1b[1;1H"); term.process(b"\x1b[99D"); term.assert_cursor(0, 0); }
798
799 #[test]
800 fn cursor_clamped_at_bottom() {
801 let mut term = HeadlessTerm::new(20, 10);
802 term.process(b"\x1b[10;1H"); term.process(b"\x1b[99B"); let (_, row) = term.cursor();
805 assert!(row <= 9, "cursor row {row} should be <= 9 (height - 1)");
806 }
807
808 #[test]
809 fn cursor_clamped_at_right() {
810 let mut term = HeadlessTerm::new(20, 10);
811 term.process(b"\x1b[1;20H"); term.process(b"\x1b[99C"); let (col, _) = term.cursor();
814 assert!(col <= 19, "cursor col {col} should be <= 19 (width - 1)");
815 }
816
817 #[test]
818 fn cursor_absolute_column_cha() {
819 let mut term = HeadlessTerm::new(20, 10);
820 term.process(b"\x1b[3;1H"); term.process(b"\x1b[8G"); term.assert_cursor(7, 2);
823 }
824
825 #[test]
826 fn cursor_absolute_row_vpa() {
827 let mut term = HeadlessTerm::new(20, 10);
828 term.process(b"\x1b[1;5H"); term.process(b"\x1b[6d"); term.assert_cursor(4, 5);
831 }
832
833 #[test]
834 fn cursor_move_then_write() {
835 let mut term = HeadlessTerm::new(20, 5);
836 term.process(b"\x1b[3;1H"); term.process(b"ABC");
838 term.process(b"\x1b[2A"); term.process(b"XY");
840 term.assert_row(0, " XY");
841 term.assert_row(2, "ABC");
842 }
843}