earl-protocol-browser 0.6.4

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
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

//! Use-case tests: screenshot capture.
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 2.1 — Screenshot produces a valid PNG.
///
/// Serves a simple HTML page, navigates to it, takes a viewport screenshot,
/// and verifies the returned base64 data decodes to a valid PNG image.
#[tokio::test]
async fn screenshot_produces_valid_png() {
    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>Hello</h1></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::Screenshot {
                path: None,
                r#type: None,
                full_page: false,
                r#ref: None,
                timeout_ms: None,
                optional: false,
            },
        ],
    };

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

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

    let data_b64 = result["data"].as_str().unwrap();
    let bytes = base64::Engine::decode(&base64::engine::general_purpose::STANDARD, data_b64)
        .expect("data should be valid base64");

    assert_eq!(
        &bytes[..4],
        &[0x89, 0x50, 0x4E, 0x47],
        "expected PNG magic bytes (\\x89PNG); got: {:?}",
        &bytes[..4]
    );
}

/// Test 2.2 — Full-page screenshot produces more data than a viewport screenshot.
///
/// Serves an HTML page containing a very tall element.  The full-page capture
/// must encode more pixels and therefore produce a longer base64 string than
/// the viewport-only capture.
#[tokio::test]
async fn full_page_screenshot_larger_than_viewport() {
    if skip_if_no_chrome() {
        return;
    }

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

    let mut routes = HashMap::new();
    routes.insert(
        "GET /".to_string(),
        Response::html(
            r#"<html><body><div style="height:5000px;background:linear-gradient(red,blue)">tall</div></body></html>"#,
        ),
    );
    let server = spawn(routes).await;

    // Command A: viewport screenshot (full_page = false).
    let data_viewport = 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::Screenshot {
                path: None,
                r#type: None,
                full_page: false,
                r#ref: None,
                timeout_ms: None,
                optional: false,
            },
        ],
    };

    let result_viewport = execute(data_viewport)
        .await
        .expect("viewport screenshot should succeed");
    let data_b64_viewport = result_viewport["data"]
        .as_str()
        .expect("viewport result should have 'data' field")
        .to_string();

    // Command B: full-page screenshot (full_page = true).
    let data_full = 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::Screenshot {
                path: None,
                r#type: None,
                full_page: true,
                r#ref: None,
                timeout_ms: None,
                optional: false,
            },
        ],
    };

    let result_full = execute(data_full)
        .await
        .expect("full-page screenshot should succeed");
    let data_b64_full_page = result_full["data"]
        .as_str()
        .expect("full-page result should have 'data' field")
        .to_string();

    assert!(
        data_b64_full_page.len() > data_b64_viewport.len(),
        "full-page screenshot ({} chars) should be larger than viewport screenshot ({} chars)",
        data_b64_full_page.len(),
        data_b64_viewport.len()
    );
}

/// Test 2.3 — Screenshot to a specified path writes the file to disk.
///
/// Passes an explicit temp-file path to the screenshot step and verifies both
/// that the returned `path` field matches the requested path and that the file
/// exists on disk after execution.
#[tokio::test]
async fn screenshot_to_specified_path_writes_file() {
    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>screenshot path test</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-screenshot-{id}.png");

    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::Screenshot {
                path: Some(path_str.clone()),
                r#type: None,
                full_page: false,
                r#ref: None,
                timeout_ms: None,
                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(),
        "screenshot file should exist on disk at {path_str}"
    );

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