diff --git a/serde_test/src/assert.rs b/serde_test/src/assert.rs index 3abb87d7..9d281faa 100644 --- a/serde_test/src/assert.rs +++ b/serde_test/src/assert.rs @@ -7,6 +7,7 @@ use token::Token; use std::fmt::Debug; +/// Runs both `assert_ser_tokens` and `assert_de_tokens`. pub fn assert_tokens(value: &T, tokens: &[Token<'static>]) where T: Serialize + Deserialize + PartialEq + Debug { @@ -14,6 +15,7 @@ pub fn assert_tokens(value: &T, tokens: &[Token<'static>]) assert_de_tokens(value, tokens); } +/// Asserts that `value` serializes to the given `tokens`. pub fn assert_ser_tokens(value: &T, tokens: &[Token]) where T: Serialize { @@ -22,7 +24,7 @@ pub fn assert_ser_tokens(value: &T, tokens: &[Token]) assert_eq!(ser.next_token(), None); } -/// Expect an error serializing `T`. +/// Asserts that `value` serializes to the given `tokens`, and then yields `error`. pub fn assert_ser_tokens_error(value: &T, tokens: &[Token], error: Error) where T: Serialize + PartialEq + Debug { @@ -32,6 +34,7 @@ pub fn assert_ser_tokens_error(value: &T, tokens: &[Token], error: Error) assert_eq!(ser.next_token(), None); } +/// Asserts that the given `tokens` deserialize into `value`. pub fn assert_de_tokens(value: &T, tokens: &[Token<'static>]) where T: Deserialize + PartialEq + Debug { @@ -41,7 +44,7 @@ pub fn assert_de_tokens(value: &T, tokens: &[Token<'static>]) assert_eq!(de.next_token(), None); } -/// Expect an error deserializing tokens into a `T`. +/// Asserts that the given `tokens` yield `error` when deserializing. pub fn assert_de_tokens_error(tokens: &[Token<'static>], error: Error) where T: Deserialize + PartialEq + Debug { diff --git a/serde_test/src/de.rs b/serde_test/src/de.rs index 2a36a28d..e975186d 100644 --- a/serde_test/src/de.rs +++ b/serde_test/src/de.rs @@ -7,6 +7,7 @@ use serde::de::value::{ValueDeserializer, MapVisitorDeserializer, SeqVisitorDese use error::Error; use token::Token; +/// A `Deserializer` that reads from a list of tokens. pub struct Deserializer where I: Iterator> { @@ -16,14 +17,17 @@ pub struct Deserializer impl Deserializer where I: Iterator> { + /// Creates the deserializer. pub fn new(tokens: I) -> Deserializer { Deserializer { tokens: tokens.peekable() } } + /// Pulls the next token off of the deserializer, ignoring it. pub fn next_token(&mut self) -> Option> { self.tokens.next() } + /// Pulls the next token off of the deserializer and checks if it matches an expected token. pub fn expect_token(&mut self, expected: Token) -> Result<(), Error> { match self.tokens.next() { Some(token) => { diff --git a/serde_test/src/error.rs b/serde_test/src/error.rs index a09252ab..507cfd46 100644 --- a/serde_test/src/error.rs +++ b/serde_test/src/error.rs @@ -5,11 +5,19 @@ use serde::{ser, de}; use token::Token; +/// Error returned by the test `Serializer` and `Deserializer`. #[derive(Clone, PartialEq, Debug)] pub enum Error { + /// A custom error. Message(String), + + /// `Deserialize` was expecting a struct of one name, and another was found. InvalidName(&'static str), + + /// `Serialize` generated a token that didn't match the test. UnexpectedToken(Token<'static>), + + /// The expected token list was too short. EndOfTokens, } diff --git a/serde_test/src/ser.rs b/serde_test/src/ser.rs index 620976a3..93608a19 100644 --- a/serde_test/src/ser.rs +++ b/serde_test/src/ser.rs @@ -5,6 +5,7 @@ use serde::{ser, Serialize}; use error::Error; use token::Token; +/// A `Serializer` that ensures that a value serializes to a given list of tokens. pub struct Serializer<'a, I> where I: Iterator> { @@ -15,6 +16,7 @@ pub struct Serializer<'a, I> impl<'a, I> Serializer<'a, I> where I: Iterator> { + /// Creates the serializer. pub fn new(tokens: I) -> Serializer<'a, I> { Serializer { tokens: tokens, @@ -22,6 +24,7 @@ impl<'a, I> Serializer<'a, I> } } + /// Pulls the next token off of the serializer, ignoring it. pub fn next_token(&mut self) -> Option<&'a Token<'a>> { self.tokens.next() } diff --git a/serde_test/src/token.rs b/serde_test/src/token.rs index b2d2a6ef..82ccd9f2 100644 --- a/serde_test/src/token.rs +++ b/serde_test/src/token.rs @@ -1,59 +1,170 @@ #[derive(Clone, PartialEq, Debug)] pub enum Token<'a> { + /// A serialized `bool`. Bool(bool), + + /// A serialized `i8`. I8(i8), + + /// A serialized `i16`. I16(i16), + + /// A serialized `i32`. I32(i32), + + /// A serialized `i64`. I64(i64), + + /// A serialized `u8`. U8(u8), + + /// A serialized `u16`. U16(u16), + + /// A serialized `u32`. U32(u32), + + /// A serialized `u64`. U64(u64), + + /// A serialized `f32`. F32(f32), + + /// A serialized `f64`. F64(f64), + + /// A serialized `char`. Char(char), + + /// A serialized `str`. Str(&'a str), + + /// A serialized `String`. String(String), + + /// A serialized `[u8]` Bytes(&'a [u8]), + + /// A serialized `ByteBuf` ByteBuf(Vec), + /// The header to a serialized `Option`. + /// + /// `None` is serialized as `Option(false)`, while `Some` is serialized as `Option(true)`, then + /// the value contained in the option. Option(bool), + /// A serialized `()`. Unit, + + /// A serialized unit struct of the given name. UnitStruct(&'a str), + /// The header to a serialized newtype struct of the given name. + /// + /// Newtype structs are serialized with this header, followed by the value contained in the + /// newtype struct. StructNewType(&'a str), + /// The header to an enum of the given name. + /// + /// This token is only used for deserializers, and ensures that the following tokens are read as + /// an enum. Because this is never emitted by serializers, calling `assert_ser_tokens` or + /// `assert_tokens` will fail if this token is used. + /// + /// TODO: Trash this. EnumStart(&'a str), + + /// A unit variant of an enum of the given name, of the given name. + /// + /// The first string represents the name of the enum, and the second represents the name of the + /// variant. EnumUnit(&'a str, &'a str), + + /// The header to a newtype variant of an enum of the given name, of the given name. + /// + /// The first string represents the name of the enum, and the second represents the name of the + /// variant. The value contained within this enum works the same as `StructNewType`. EnumNewType(&'a str, &'a str), + /// The header to a sequence of the given length. + /// + /// These are serialized via `serialize_seq`, which takes an optional length. After this + /// header is a list of elements, followed by `SeqEnd`. SeqStart(Option), + + /// The header to an array of the given length. + /// + /// These are serialized via `serialize_seq_fized_size`, which requires a length. After this + /// header is a list of elements, followed by `SeqEnd`. SeqArrayStart(usize), + + /// A separator, which occurs *before* every element in a sequence. + /// + /// Elements in sequences are represented by a `SeqSep`, followed by the value of the element. SeqSep, + + /// An indicator of the end of a sequence. SeqEnd, + /// The header to a tuple of the given length, similar to `SeqArrayStart`. TupleStart(usize), + + /// A separator, similar to `SeqSep`. TupleSep, + + /// An indicator of the end of a tuple, similar to `SeqEnd`. TupleEnd, + /// The header to a tuple struct of the given name and length. TupleStructStart(&'a str, usize), + + /// A separator, similar to `TupleSep`. TupleStructSep, + + /// An indicator of the end of a tuple struct, similar to `TupleEnd`. TupleStructEnd, + /// The header to a map of the given length. + /// + /// These are serialized via `serialize_map`, which takes an optional length. After this header + /// is a list of key-value pairs, followed by `MapEnd`. MapStart(Option), + + /// A separator, which occurs *before* every key-value pair in a map. + /// + /// Elements in maps are represented by a `MapSep`, followed by a serialized key, followed + /// by a serialized value. MapSep, + + /// An indicator of the end of a map. MapEnd, + /// The header of a struct of the given name and length, similar to `MapStart`. StructStart(&'a str, usize), + + /// A separator, similar to `MapSep`. StructSep, + + /// An indicator of the end of a struct, similar to `MapEnd`. StructEnd, + /// The header to a tuple variant of an enum of the given name, of the given name and length. EnumSeqStart(&'a str, &'a str, usize), + + /// A separator, similar to `TupleSep`. EnumSeqSep, + + /// An indicator of the end of a tuple variant, similar to `TupleEnd`. EnumSeqEnd, + /// The header of a struct variant of an enum of the given name, of the given name and length, + /// similar to `StructStart`. EnumMapStart(&'a str, &'a str, usize), + + /// A separator, similar to `StructSep`. EnumMapSep, + + /// An indicator of the end of a struct, similar to `StructEnd`. EnumMapEnd, }