Subunit Rust

This repo contains a implementation of the subunit v2 protocol in Rust. It provides an interface for both writing and reading subunit streams natively in rust. The subunit v2 protocol is documented in the testing-cabal/subunit repository.

Reading subunit packets

Reading subunit packets first requires an object implementing the Read trait containing the subunit stream. The parse_subunit() function is used to first buffer the entire stream in memory, and then parse the contents and return a vector of Event structs. For example, parsing a subunit stream from a file:

    let mut f = File::open("results.subunit")?;
    let events = parse_subunit(f).unwrap();

In this example, the results.subunit file will be opened and parsed with an Event struct in the events vector for each subunit packet in the file.

Writing subunit packets

Writing a subunit packet first requires creating an event structure to describe the contents of the packet. For example:

    let mut event_start = Event {
        status: Some("inprogress".to_string()),
        test_id: Some("A_test_id".to_string()),
        timestamp: Some(Utc.ymd(2014, 7, 8).and_hms(9, 10, 11)),
        tags: Some(vec!["tag_a".to_string(), "tag_b".to_string()]),
        file_content: None,
        file_name: None,
        mime_type: None,
        route_code: None
    };

A typical test event normally involves 2 packets though, one to mark the start and the other to mark the finish of a test:

    let mut event_end = Event {
        status: Some("success".to_string()),
        test_id: Some("A_test_id".to_string()),
        timestamp: Some(Utc.ymd(2014, 7, 8).and_hms(9, 12, 0)),
        tags: Some(vec!["tag_a".to_string(), "tag_b".to_string()]),
        file_content: Some("stdout content".to_string().into_bytes()),
        file_name: Some("stdout:''".to_string()),
        mime_type: Some("text/plain;charset=utf8".to_string()),
        route_code: None
    };

Then you'll want to write the packet out to something. Anything that implements the std::io::Write trait can be used for the packets, including things like a File and a TCPStream. In this case we'll use Vec to keep it in memory:

    let mut subunit_stream: Vec<u8> = Vec::new();

    subunit_stream = event_start.write(subunit_stream)?;
    subunit_stream = event_end.write(subunit_stream)?;

With this the subunit_stream buffer will contain the contents of the subunit stream for that test event.