quick_junit/
lib.rs

1// Copyright (c) The nextest Contributors
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4#![warn(missing_docs)]
5
6//! `quick-junit` is a JUnit/XUnit XML data model and serializer for Rust. This crate allows users
7//! to create a JUnit report as an XML file. JUnit XML files are widely supported by test tooling.
8//!
9//!  This crate is built to serve the needs of [cargo-nextest](https://nexte.st).
10//!
11//! # Overview
12//!
13//! The root element of a JUnit report is a [`Report`]. A [`Report`] consists of one or more
14//! [`TestSuite`] instances. A [`TestSuite`] instance consists of one or more [`TestCase`]s.
15//!
16//! The status (success, failure, error, or skipped) of a [`TestCase`] is represented by
17//! [`TestCaseStatus`].
18//!
19//! # Features
20//!
21//! - ✅ Serializing JUnit/XUnit to the [Jenkins format](https://llg.cubic.org/docs/junit/).
22//! - ✅ Deserializing JUnit/XUnit XML back to Rust data structures
23//! - ✅ Including test reruns using [`TestRerun`]
24//! - ✅ Including flaky tests
25//! - ✅ Including standard output and error
26//!   - ✅ Filtering out [invalid XML
27//!     characters](https://en.wikipedia.org/wiki/Valid_characters_in_XML) (eg ANSI escape codes)
28//!     from the output
29//! - ✅ Automatically keeping track of success, failure, error, and skipped counts
30//! - ✅ Arbitrary properties and extra attributes
31//!
32//! # Examples
33//!
34//! ```rust
35//! use quick_junit::*;
36//!
37//! let mut report = Report::new("my-test-run");
38//! let mut test_suite = TestSuite::new("my-test-suite");
39//! let success_case = TestCase::new("success-case", TestCaseStatus::success());
40//! let failure_case = TestCase::new("failure-case", TestCaseStatus::non_success(NonSuccessKind::Failure));
41//! test_suite.add_test_cases([success_case, failure_case]);
42//! report.add_test_suite(test_suite);
43//!
44//! const EXPECTED_XML: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
45//! <testsuites name="my-test-run" tests="2" skipped="0" failures="1" errors="0">
46//!     <testsuite name="my-test-suite" tests="2" skipped="0" errors="0" failures="1">
47//!         <testcase name="success-case"/>
48//!         <testcase name="failure-case">
49//!             <failure/>
50//!         </testcase>
51//!     </testsuite>
52//! </testsuites>
53//! "#;
54//!
55//! assert_eq!(report.to_string().unwrap(), EXPECTED_XML);
56//! ```
57//!
58//! For a more comprehensive example, including reruns and flaky tests, see
59//! [`fixture_tests.rs`](https://github.com/nextest-rs/quick-junit/blob/main/crates/quick-junit-tests/tests/integration/fixture_tests.rs).
60//!
61//! # Optional features
62//!
63//! - **proptest**: Generate `Arbitrary` instances for use with proptest. *Not enabled by default.*
64//!
65//! # Minimum supported Rust version (MSRV)
66//!
67//! The minimum supported Rust version is **Rust 1.79.** At any time, Rust versions from at least
68//! the last 6 months will be supported.
69//!
70//! While this crate is a pre-release (0.x.x) it may have its MSRV bumped in a patch release. Once a
71//! crate has reached 1.x, any MSRV bump will be accompanied with a new minor version.
72//!
73//! # Alternatives
74//!
75//! - [**junit-report**](https://crates.io/crates/junit-report): Older, more mature project. Doesn't
76//!   appear to support flaky tests or arbitrary properties as of version 0.8.3.
77
78mod deserialize;
79mod errors;
80mod report;
81mod serialize;
82
83#[cfg(feature = "proptest")]
84mod proptest_impls;
85
86pub use errors::*;
87pub use report::*;
quick_junit/lib.rs

quick_junit/
lib.rs
