[quick-junit] expand readme

sunshowers · Jan 29, 2022 · 25ee11d · 25ee11d
1 parent e5f9060
commit 25ee11d
Show file tree

Hide file tree

Showing 5 changed files with 59 additions and 11 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/quick-junit/CHANGELOG.md b/quick-junit/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.1.2] - 2022-01-29
+
+- Expand readme.
+- Add keywords and categories.
+
 ## [0.1.1] - 2022-01-28
 
 - Fix repository field in Cargo.toml.
@@ -8,5 +13,6 @@
 
 - Initial version.
 
+[0.1.2]: https://github.com/diem/diem-devtools/releases/tag/quick-junit-0.1.2
 [0.1.1]: https://github.com/diem/diem-devtools/releases/tag/quick-junit-0.1.1
 [0.1.0]: https://github.com/diem/diem-devtools/releases/tag/quick-junit-0.1.0
diff --git a/quick-junit/Cargo.toml b/quick-junit/Cargo.toml
@@ -1,12 +1,14 @@
 [package]
 name = "quick-junit"
-description = "Serializer for JUnit/XUnit XML"
-version = "0.1.1"
+description = "Data model and serializer for JUnit/XUnit XML"
+version = "0.1.2"
 authors = ["Diem Association <opensource@diem.com>"]
 readme = "README.md"
 license = "Apache-2.0 OR MIT"
 repository = "https://github.com/diem/diem-devtools"
 documentation = "https://docs.rs/quick-junit"
+keywords = ["junit", "xunit", "xml", "serializer", "flaky-tests"]
+categories = ["encoding", "development-tools"]
 edition = "2021"
 
 [dependencies]

diff --git a/quick-junit/README.md b/quick-junit/README.md
@@ -7,16 +7,31 @@
 [![License](https://img.shields.io/badge/license-Apache-green.svg)](LICENSE-APACHE)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE-MIT)
 
-`quick-junit` is a JUnit/XUnit XML serializer for Rust. This crate is built to serve the needs
-of [cargo-nextest](docs.rs/cargo-nextest).
+`quick-junit` is a JUnit/XUnit XML data model and serializer for Rust. This crate allows users
+to create a JUnit report as an XML file. JUnit XML files are widely supported by test tooling.
+
+ This crate is built to serve the needs of [cargo-nextest](docs.rs/cargo-nextest).
 
 ## Overview
 
 The root element of a JUnit report is a `Report`. A `Report` consists of one or more
 `TestSuite` instances. A `TestSuite` instance consists of one or more `TestCase`s.
 
 The status (success, failure, error, or skipped) of a `TestCase` is represented by `TestCaseStatus`.
-If a test was rerun, `TestCaseStatus` can manage `TestRerun` instances as well.
+
+## Features
+
+- x Serializing JUnit/XUnit to the [Jenkins format](https://llg.cubic.org/docs/junit/).
+- x Including test reruns using `TestRerun`
+- x Including flaky tests
+- x Including standard output and error
+  - x Filtering out [invalid XML
+    characters](https://en.wikipedia.org/wiki/Valid_characters_in_XML) (eg ANSI escape codes)
+    from the output
+- x Automatically keeping track of success, failure and error counts
+- x Arbitrary properties and extra attributes
+
+This crate does not currently support deserializing JUnit XML. (PRs are welcome!)
 
 ## Examples
 
@@ -45,9 +60,14 @@ const EXPECTED_XML: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
 assert_eq!(report.to_string().unwrap(), EXPECTED_XML);
 ```
 
-For a more comprehensive example, see
+For a more comprehensive example, including reruns and flaky tests, see
 [`fixture_tests.rs`](https://github.com/diem/diem-devtools/blob/main/quick-junit/tests/fixture_tests.rs).
 
+## Alternatives
+
+* [**junit-report**](https://crates.io/crates/junit-report): Older, more mature project. Doesn't
+  appear to support flaky tests or arbitrary properties as of version 0.7.0.
+
 ## Contributing
 
 See the [CONTRIBUTING](CONTRIBUTING.md) file for how to help out.

diff --git a/quick-junit/src/lib.rs b/quick-junit/src/lib.rs
@@ -3,16 +3,31 @@
 
 #![warn(missing_docs)]
 
-//! `quick-junit` is a JUnit/XUnit XML serializer for Rust. This crate is built to serve the needs
-//! of [cargo-nextest](docs.rs/cargo-nextest).
+//! `quick-junit` is a JUnit/XUnit XML data model and serializer for Rust. This crate allows users
+//! to create a JUnit report as an XML file. JUnit XML files are widely supported by test tooling.
+//!
+//!  This crate is built to serve the needs of [cargo-nextest](docs.rs/cargo-nextest).
 //!
 //! # Overview
 //!
 //! The root element of a JUnit report is a [`Report`]. A [`Report`] consists of one or more
 //! [`TestSuite`] instances. A [`TestSuite`] instance consists of one or more [`TestCase`]s.
 //!
 //! The status (success, failure, error, or skipped) of a [`TestCase`] is represented by [`TestCaseStatus`].
-//! If a test was rerun, [`TestCaseStatus`] can manage [`TestRerun`] instances as well.
+//!
+//! # Features
+//!
+//! - [x] Serializing JUnit/XUnit to the [Jenkins format](https://llg.cubic.org/docs/junit/).
+//! - [x] Including test reruns using [`TestRerun`]
+//! - [x] Including flaky tests
+//! - [x] Including standard output and error
+//!   - [x] Filtering out [invalid XML
+//!     characters](https://en.wikipedia.org/wiki/Valid_characters_in_XML) (eg ANSI escape codes)
+//!     from the output
+//! - [x] Automatically keeping track of success, failure and error counts
+//! - [x] Arbitrary properties and extra attributes
+//!
+//! This crate does not currently support deserializing JUnit XML. (PRs are welcome!)
 //!
 //! # Examples
 //!
@@ -41,8 +56,13 @@
 //! assert_eq!(report.to_string().unwrap(), EXPECTED_XML);
 //! ```
 //!
-//! For a more comprehensive example, see
+//! For a more comprehensive example, including reruns and flaky tests, see
 //! [`fixture_tests.rs`](https://github.com/diem/diem-devtools/blob/main/quick-junit/tests/fixture_tests.rs).
+//!
+//! # Alternatives
+//!
+//! * [**junit-report**](https://crates.io/crates/junit-report): Older, more mature project. Doesn't
+//!   appear to support flaky tests or arbitrary properties as of version 0.7.0.
 
 mod report;
 mod serialize;