Skip to content

Commit

Permalink
Book tips and best practices (#367)
Browse files Browse the repository at this point in the history
* Add book page for Tips and Best Practices.

For now, just a few performance tips but eventually we'll want
to add other things.

* Revamp book theme and run `mdbook test` and update code blocks
  • Loading branch information
hamiltop authored Sep 11, 2023
1 parent fc3be95 commit fcccad0
Show file tree
Hide file tree
Showing 30 changed files with 362 additions and 1,827 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/gh-pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ jobs:
- name: Setup mdBook
uses: peaceiris/actions-mdbook@v1
with:
mdbook-version: "0.4.18"
mdbook-version: "0.4.34"

- run: cd book && mdbook build

Expand Down
1 change: 0 additions & 1 deletion book/book.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
[book]
authors = ["Jason Lingle", "Mazdak Farrokhzad"]
multilingual = false
src = "src"
title = "Proptest"
description = "Usage documentation for the proptest and proptest-derive crates"
Expand Down
1 change: 1 addition & 0 deletions book/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
- [Proptest vs Quickcheck](proptest/vs-quickcheck.md)
- [Reference documentation](proptest/reference-docs.md)
- [State Machine testing](proptest/state-machine.md)
- [Tips and Best Practices](proptest/tips-and-best-practices.md)

- [proptest-derive](proptest-derive/index.md)
- [Getting started](proptest-derive/getting-started.md)
Expand Down
71 changes: 36 additions & 35 deletions book/src/proptest-derive/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
This error occurs when `#[derive(Arbitrary)]` is used on a type which has any
[lifetime parameters]. For example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo<'a> {
bar: &'a str,
Expand All @@ -31,7 +31,7 @@ To follow the progress, consult the [tracking issue][issue#9] on the matter.
This error occurs when `#[derive(Arbitrary)]` is used on a `union` type.
An example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
union IU32 {
signed: i32,
Expand Down Expand Up @@ -62,7 +62,7 @@ in turn means the struct itself is uninhabited and so it there is no sensible

A trivial example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Uninhabited {
inhabited: u32,
Expand All @@ -83,7 +83,7 @@ be inhabited and you will instead get an error about the type not implementing
This error occurs when `#[derive(Arbitrary)]` is used on an enum with no
variants at all. For example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
enum Uninhabited {}
```
Expand All @@ -99,7 +99,7 @@ As a result, the enum itself is totally uninhabited.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
enum Uninhabited {
Never(!),
Expand All @@ -116,7 +116,7 @@ enum itself cannot be generated.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
enum MyEnum {
// Ordinarily, proptest would be able to generate either of these variants,
Expand All @@ -140,7 +140,7 @@ This error happens if an attribute [`#[proptest(strategy = "expr")]`] or

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
#[proptest(value = "MyStruct(42)")]
struct MyStruct(u32);
Expand All @@ -157,7 +157,7 @@ of a struct to have a value.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct WidgetContainer {
desired_widget_count: usize,
Expand All @@ -170,7 +170,7 @@ In general, the appropriate way to request proptest to not generate a field
value is to use [`#[proptest(value = "expr")]`] to provide a fixed value
yourself. For example, the above code could be properly written as follows:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct WidgetContainer {
desired_widget_count: usize,
Expand All @@ -184,7 +184,7 @@ struct WidgetContainer {
This error happens if [`#[proptest(weight = <integer>)]`] is applied to an item
where this does not make sense, such as a struct field. For example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Point {
x: u32,
Expand All @@ -204,7 +204,7 @@ This error occurs if [`#[proptest(params = "type")]`] and/or

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
#[proptest(params = "String")]
struct Foo {
Expand All @@ -223,7 +223,7 @@ This error occurs if [`#[proptest(params = "type")]`] is set on a field but no
explicit strategy is configured with [`#[proptest(strategy = "expr")]`] or
another such modifier. For example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo {
#[proptest(param = "u8")]
Expand All @@ -248,7 +248,7 @@ would thus occur without consulting the filter.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
enum Foo {
#[proptest(value = "Foo::Bar(42)")]
Expand Down Expand Up @@ -279,7 +279,7 @@ since it has no meaningful content.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo {
#[proptest]
Expand All @@ -296,7 +296,7 @@ encountered in any context.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo {
#[proptest = 1234]
Expand All @@ -311,7 +311,7 @@ This error occurs if a literal (as opposed to `key = value`) is passed inside

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo {
#[proptest(1234)]
Expand All @@ -326,7 +326,7 @@ the same item.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
#[proptest(no_params, no_params)]
struct Foo(u32);
Expand All @@ -338,7 +338,7 @@ This error occurs if an unknown modifier is passed in `#[proptest(..)]`.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
#[proptest(frobnicate = "true")]
struct Foo(u32);
Expand All @@ -353,7 +353,7 @@ This error happens if anything extra is passed to [`#[proptest(no_params)]`].

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
#[proptest(no_params = "true")]
struct Foo(u32);
Expand All @@ -368,7 +368,7 @@ This error happens if anything extra is passed to [`#[proptest(skip)]`].

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
enum Foo {
Small,
Expand All @@ -386,7 +386,7 @@ integer or passed nothing at all.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
enum Foo {
#[proptest(weight)]
Expand All @@ -407,7 +407,7 @@ This error occurs if more than one of [`#[proptest(no_params)]`] and

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
#[proptest(no_params, params = "u8")]
struct Foo(u32);
Expand All @@ -422,7 +422,7 @@ applied to an item.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
#[proptest(params = "Vec<u8")] // Note missing '>'
struct Foo(u32);
Expand Down Expand Up @@ -453,7 +453,7 @@ to the same item.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo {
#[proptest(value = "42", strategy = "Just(56)")]
Expand All @@ -472,7 +472,7 @@ This error happens if an invalid form of [`#[proptest(strategy = "expr")]`] or

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo {
#[proptest(value = "3↑↑↑↑3")] // String content is not valid Rust syntax
Expand All @@ -496,7 +496,7 @@ used.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo {
#[proptest(filter = "> 3")] // String content is not an expression
Expand All @@ -520,7 +520,8 @@ applied to an enum variant which is also marked [`#[proptest(skip)]`].

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
enum Enum {
V1(u32),
Expand All @@ -540,7 +541,7 @@ of an enum variant is to be generated is applied to a unit variant.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
enum Foo {
#[proptest(value = "Foo::V1")]
Expand All @@ -560,7 +561,7 @@ of a struct is to be generated is applied to a unit struct.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
#[proptest(params = "u8")]
struct UnitStruct;
Expand All @@ -577,7 +578,7 @@ not a type variable.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo {
#[proptest(no_bound)]
Expand All @@ -587,7 +588,7 @@ struct Foo {

The `no_bound` modifier only makes sense on generic type variables, as in

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo<#[proptest(no_bound)] T> {
#[proptest(value = "None")]
Expand All @@ -601,7 +602,7 @@ This error happens if [`#[proptest(no_bound)]`] is passed anything.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
struct Foo<#[proptest(no_bound = "yes")] T> {
_bar: PhantomData<T>,
Expand All @@ -617,7 +618,7 @@ a `u32`.

Example:

```rust
```rust,compile_fail
#[derive(Debug, Arbitrary)]
enum Foo {
#[proptest(weight = 3_000_000_000)]
Expand Down Expand Up @@ -655,7 +656,7 @@ couple ways depending on what the syntax is describing:

For types, simply define a type alias for the type in question. For example,

```rust
```rust,compile_fail
type RetroBox = ~str; // N.B. "~str" is not valid Rust 1.30 syntax
//...
Expand All @@ -667,7 +668,7 @@ struct MyStruct { /* ... */ }
For values, you can generally factor the code into a constant or function. For
example,

```rust
```rust,compile_fail
// N.B. Rust 1.30 does not have an exponentiation operator.
const PI_SQUARED: f64 = PI ** 2.0;
Expand Down
Loading

0 comments on commit fcccad0

Please sign in to comment.