brlapi 0.4.1

Safe Rust bindings for the BrlAPI library
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

// SPDX-License-Identifier: LGPL-2.1

//! Common test utilities for BrlAPI high-level wrapper tests
//!
//! Note: Some functions may appear unused due to cross-test-file usage not being
//! detected by the compiler, but they are used by different test binaries.

#![allow(dead_code)] // Suppress false positive warnings for cross-test-file usage

use brlapi::{BrlApiError, Connection, ConnectionSettings, TtyMode};

/// Test helper to create a connection and handle expected failures gracefully
pub fn try_connect() -> Result<Connection, BrlApiError> {
    Connection::open()
}

/// Test helper to create a connection with specific settings
pub fn try_connect_with_settings(settings: &ConnectionSettings) -> Result<Connection, BrlApiError> {
    Connection::open_with_settings(Some(settings))
}

/// Create localhost connection settings for testing
pub fn localhost_settings() -> ConnectionSettings {
    ConnectionSettings::localhost()
}

/// Create IPv4 connection settings for testing
pub fn ipv4_settings() -> ConnectionSettings {
    ConnectionSettings::for_host("127.0.0.1")
}

/// Test helper that runs a test with a connection if available
pub fn with_connection<F, R>(test_fn: F) -> Option<R>
where
    F: FnOnce(Connection) -> R,
{
    match try_connect() {
        Ok(conn) => {
            println!("Connection established for test");
            Some(test_fn(conn))
        }
        Err(e) => {
            println!("No connection available for test: {e}");
            None
        }
    }
}

/// Test helper that runs a test with a connection in TTY mode if possible
pub fn with_tty_mode<F, R>(test_fn: F) -> Option<R>
where
    F: FnOnce(&Connection) -> Result<R, BrlApiError>,
{
    with_connection(|conn| {
        match TtyMode::try_from(&conn) {
            Ok(_tty_mode) => {
                println!("TTY mode entered for test");
                let result = test_fn(&conn);
                // TTY mode automatically cleaned up when _tty_mode drops
                result
            }
            Err(e) => {
                println!("TTY mode not available for test: {e}");
                Err(e)
            }
        }
    })
    .and_then(|r| r.ok())
}

/// Assert that a connection method returns reasonable values or expected errors
pub fn assert_reasonable_result<T: std::fmt::Debug>(
    result: Result<T, BrlApiError>,
    operation_name: &str,
) -> Option<T> {
    match result {
        Ok(value) => {
            println!("{operation_name}: Success");
            Some(value)
        }
        Err(BrlApiError::OperationNotSupported)
        | Err(BrlApiError::ConnectionRefused)
        | Err(BrlApiError::TTYBusy)
        | Err(BrlApiError::DeviceBusy) => {
            println!("{operation_name}: Expected error: {}", result.unwrap_err());
            None
        }
        Err(e) => {
            println!("{operation_name}: Unexpected error: {e}");
            None
        }
    }
}

/// Create test data for various scenarios
pub mod test_data {

    pub fn sample_texts() -> Vec<&'static str> {
        vec![
            "Hello BrlAPI",
            "Test message",
            "", // Empty text
            "This is a very long text that exceeds typical braille display width",
            "Unicode: 测试 العربية",
        ]
    }

    pub fn cursor_positions() -> Vec<i32> {
        vec![
            brlapi_sys::BRLAPI_CURSOR_LEAVE,
            brlapi_sys::BRLAPI_CURSOR_OFF as i32,
            0,
            5,
            10,
        ]
    }
}