earl-protocol-browser 0.6.2

Browser automation protocol for earl (chromiumoxide)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

//! Use-case tests: PDF save.
mod common;
use common::{Response, execute, skip_if_no_chrome, spawn};
use earl_protocol_browser::PreparedBrowserCommand;
use earl_protocol_browser::schema::BrowserStep;
use std::collections::HashMap;

fn unique_id() -> String {
    use std::sync::atomic::{AtomicU64, Ordering};
    static COUNTER: AtomicU64 = AtomicU64::new(0);
    let count = COUNTER.fetch_add(1, Ordering::Relaxed);
    format!("{}-{}", std::process::id(), count)
}

/// Test 8.1 — pdf_save writes a valid PDF to disk.
///
/// Serves an HTML invoice page, requests a PDF at an explicit temp path, and
/// verifies that the file exists and starts with the PDF magic bytes `%PDF`.
#[tokio::test]
async fn pdf_save_writes_valid_pdf_to_disk() {
    if skip_if_no_chrome() {
        return;
    }

    let _guard = common::chrome_lock().await;

    let mut routes = HashMap::new();
    routes.insert(
        "GET /".to_string(),
        Response::html("<html><body><h1>Invoice #001</h1><p>Total: $42.00</p></body></html>"),
    );
    let server = spawn(routes).await;

    let id = unique_id();
    // Use a relative path — validate_file_path rejects absolute paths.
    let path_str = format!("earl-test-invoice-{id}.pdf");

    let data = PreparedBrowserCommand {
        session_id: None,
        headless: true,
        timeout_ms: 30_000,
        on_failure_screenshot: false,
        steps: vec![
            BrowserStep::Navigate {
                url: server.url("/"),
                expected_status: None,
                timeout_ms: None,
                optional: false,
            },
            BrowserStep::PdfSave {
                path: Some(path_str.clone()),
                optional: false,
            },
        ],
    };

    let result = execute(data).await.expect("execute should succeed");

    assert_eq!(
        result["path"].as_str(),
        Some(path_str.as_str()),
        "result 'path' field should match the requested path; got: {}",
        result["path"]
    );
    assert!(
        std::path::Path::new(&path_str).exists(),
        "PDF file should exist on disk at {path_str}"
    );

    // Verify the PDF magic bytes: %PDF = [0x25, 0x50, 0x44, 0x46]
    let bytes = std::fs::read(&path_str).expect("should be able to read the PDF file");
    assert!(
        bytes.len() >= 4,
        "PDF file should contain at least 4 bytes; got {} bytes",
        bytes.len()
    );
    assert_eq!(
        &bytes[..4],
        &[0x25, 0x50, 0x44, 0x46],
        "expected PDF magic bytes (%PDF); got: {:?}",
        &bytes[..4]
    );

    std::fs::remove_file(&path_str).ok();
}

/// Test 8.2 — pdf_save with no path returns base64 data without writing a file.
///
/// Omits the `path` field.  The executor must return `{"data": "<base64>",
/// "size": N}` without touching the file system.  The base64 data must decode
/// to valid PDF bytes (magic header `%PDF`).
#[tokio::test]
async fn pdf_save_no_path_returns_base64_data() {
    if skip_if_no_chrome() {
        return;
    }

    let _guard = common::chrome_lock().await;

    let mut routes = HashMap::new();
    routes.insert(
        "GET /".to_string(),
        Response::html("<html><body><p>base64 PDF test</p></body></html>"),
    );
    let server = spawn(routes).await;

    let data = PreparedBrowserCommand {
        session_id: None,
        headless: true,
        timeout_ms: 30_000,
        on_failure_screenshot: false,
        steps: vec![
            BrowserStep::Navigate {
                url: server.url("/"),
                expected_status: None,
                timeout_ms: None,
                optional: false,
            },
            BrowserStep::PdfSave {
                path: None,
                optional: false,
            },
        ],
    };

    let result = execute(data).await.expect("execute should succeed");

    // No path given — result must have `data`, not `path`.
    assert!(
        result["path"].is_null(),
        "result should NOT have a 'path' field when no path is given; got: {result}"
    );

    let data_b64 = result["data"]
        .as_str()
        .expect("result should have a non-null 'data' field");
    assert!(!data_b64.is_empty(), "base64 data should be non-empty");

    let size = result["size"]
        .as_u64()
        .expect("result should have a numeric 'size' field");
    assert!(size > 0, "size should be greater than 0");

    // Decode and verify PDF magic bytes: %PDF = [0x25, 0x50, 0x44, 0x46]
    let bytes = base64::Engine::decode(&base64::engine::general_purpose::STANDARD, data_b64)
        .expect("data should be valid base64");
    assert!(
        bytes.len() >= 4,
        "decoded PDF should have at least 4 bytes; got {}",
        bytes.len()
    );
    assert_eq!(
        &bytes[..4],
        &[0x25, 0x50, 0x44, 0x46],
        "expected PDF magic bytes (%PDF); got: {:?}",
        &bytes[..4]
    );
}