testutil

Documentation

Overview

Package testutil is a collection of testing helper methods.

Index

• func BytesCompare(a, b []byte) (sa, sb string, ok bool)
• func DecodeBitGen(s string) ([]byte, error)
• func MustDecodeBitGen(s string) []byte
• func MustDecodeHex(s string) []byte
• func MustLoadFile(file string) []byte
• func ResizeData(input []byte, n int) []byte
• type BuggyReader
  • func (br *BuggyReader) Read(buf []byte) (int, error)
• type BuggyWriter
  • func (bw *BuggyWriter) Write(buf []byte) (int, error)
• type Rand
  • func NewRand(seed int) *Rand
  • func (r *Rand) Bytes(n int) []byte
  • func (r *Rand) Int() int
  • func (r *Rand) Intn(n int) int
  • func (r *Rand) Perm(n int) []int

Functions

func BytesCompare

func BytesCompare(a, b []byte) (sa, sb string, ok bool)

BytesCompare compares inputs a and b and reports whether they are equal.

If they are not equal, it returns two one-line strings that are representative of the differences between the two strings. The output will be quoted strings if it seems like the data is text, otherwise, it will use hexadecimal strings.

Example usage:

if got, want, ok := testutil.BytesCompare(output, v.output); !ok {
	t.Errorf("output mismatch:\ngot  %s\nwant %s", got, want)
}

func DecodeBitGen

func DecodeBitGen(s string) ([]byte, error)

DecodeBitGen decodes a BitGen formatted string.

The BitGen format allows bit-streams to be generated from a series of tokens describing bits in the resulting string. The format is designed for testing purposes by aiding a human in the manual scripting of a compression stream from individual bit-strings. It is designed to be relatively succinct, but allow the user to have control over the bit-order and also to allow the presence of comments to encode authorial intent.

The format consists of a series of tokens delimited by either whitespace, a group marker, or a comment. As a special case, delimiters within a quoted string do not separate tokens. The '#' character is used for commenting such that any remaining bytes on the given line is ignored.

The first valid token must either be a "<<<" (little-endian) or a ">>>" (big-endian). This determines whether the preceding bits in the stream are packed starting with the least-significant bits of a byte (little-endian) or packed starting with the most-significant bits of a byte (big-endian). Formats like DEFLATE and Brotli use little-endian, while BZip2 uses a big-endian bit-packing mode. This token appears exactly once at the start.

A token of the form "<" (little-endian) or ">" (big-endian) determines the current bit-parsing mode, which alters the way subsequent tokens are processed. The format defaults to using a little-endian bit-parsing mode.

A token of the pattern "[01]{1,64}" forms a bit-string (e.g. 11010). If the current bit-parsing mode is little-endian, then the right-most bits of the bit-string are written first to the resulting bit-stream. Likewise, if the bit-parsing mode is big-endian, then the left-most bits of the bit-string are written first to the resulting bit-stream.

A token of the pattern "D[0-9]+:[0-9]+" or "H[0-9]+:[0-9a-fA-F]{1,16}" represents either a decimal value or a hexadecimal value, respectively. This numeric value is converted to the unsigned binary representation and used as the bit-string to write. The first number indicates the bit-length of the bit-string and must be between 0 and 64 bits. The second number represents the numeric value. The bit-length must be long enough to contain the resulting binary value. If the current bit-parsing mode is little-endian, then the least-significant bits of this binary number are written first to the resulting bit-stream. Likewise, the opposite holds for big-endian mode.

A token that is of the pattern "X:[0-9a-fA-F]+" represents literal bytes in hexadecimal format that should be written to the resulting bit-stream. This token is affected by neither the bit-packing nor the bit-parsing modes. However, it may only be used when the bit-stream is currently byte-aligned.

A token that begins and ends with a '"' represents literal bytes in human readable form. This double-quoted string is parsed in the same way that the Go language parses strings. Any delimiter tokens within the context of a quoted string have no effect. This token is affected by neither the bit-packing nor the bit-parsing modes. However, it may only be used when the bit-stream is already byte-aligned.

A token decorator of "<" (little-endian) or ">" (big-endian) may begin any binary token or decimal token. This will affect the bit-parsing mode for that token only. It will not set the overall global mode (that still needs to be done by standalone "<" and ">" tokens). This decorator may not applied to the literal bytes token.

A token decorator of the pattern "[*][0-9]+" may trail any token except for standalone "<" or ">" tokens. This is a quantifier decorator which indicates that the current token is to be repeated some number of times. It is used to quickly replicate data and allows the format to quickly generate large quantities of data.

A sequence of tokens may be grouped together by enclosing them in a pair of "(" and ")" characters. Any standalone "<" or ">" tokens only take effect within the context of that group. A group with a "<" or ">" decorator is equivalent to having that as the first standalone token in the sequence. A repeator decorator on a group causes that group to be executed the specified number of times.

If the total bit-stream does not end on a byte-aligned edge, then the stream will automatically be padded up to the nearest byte with 0 bits.

Example BitGen file:

<<< # DEFLATE uses LE bit-packing order

( # Raw blocks
	< 0 00 0*5                 # Non-last, raw block, padding
	< H16:0004 H16:fffb        # RawSize: 4
	X:deadcafe                 # Raw data
)*2

( # Dynamic block
	< 1 10                     # Last, dynamic block
	< D5:1 D5:0 D4:15          # HLit: 258, HDist: 1, HCLen: 19
	< 000*3 001 000*13 001 000 # HCLens: {0:1, 1:1}
	> 0*256 1*2                # HLits: {256:1, 257:1}
	> 0                        # HDists: {}
	> 1 0                      # Use invalid HDist code 0
)

Generated output stream (in hexadecimal):

000400fbffdeadcafe000400fbffdeadcafe0de0010400000000100000000000
0000000000000000000000000000000000000000000000000000002c

func MustDecodeBitGen

func MustDecodeBitGen(s string) []byte

MustDecodeBitGen must decode a BitGen formatted string or else panics.

func MustDecodeHex

func MustDecodeHex(s string) []byte

MustDecodeHex must decode a hexadecimal string or else panics.

func MustLoadFile

func MustLoadFile(file string) []byte

MustLoadFile must load a file or else panics.

func ResizeData

func ResizeData(input []byte, n int) []byte

ResizeData resizes the input. If n < 0, then the original input will be returned as is. If n <= len(input), then the input slice will be truncated. However, if n > len(input), then the input will be replicated to fill in the missing bytes, but each replicated string will be XORed by some byte mask to avoid favoring algorithms with large LZ77 windows.

If n > len(input), then len(input) must be > 0.

Types

type BuggyReader

type BuggyReader struct {
	R   io.Reader
	N   int64 // Number of valid bytes to read
	Err error // Return this error after N bytes
}

BuggyReader returns Err after N bytes have been read from R.

func (*BuggyReader) Read

func (br *BuggyReader) Read(buf []byte) (int, error)

type BuggyWriter

type BuggyWriter struct {
	W   io.Writer
	N   int64 // Number of valid bytes to write
	Err error // Return this error after N bytes
}

BuggyWriter returns Err after N bytes have been written to W.

func (*BuggyWriter) Write

func (bw *BuggyWriter) Write(buf []byte) (int, error)

type Rand

type Rand struct {
	cipher.Block
	// contains filtered or unexported fields
}

Rand implements a deterministic pseudo-random number generator. This differs from the math.Rand in that the exact output will be consistent across different versions of Go.

func NewRand

func NewRand(seed int) *Rand

func (*Rand) Bytes

func (r *Rand) Bytes(n int) []byte

func (*Rand) Int

func (r *Rand) Int() int

func (*Rand) Intn

func (r *Rand) Intn(n int) int

func (*Rand) Perm

func (r *Rand) Perm(n int) []int