roboservant

Automatically fuzz your servant apis in a contextually-aware way.

example

see full example here

why?

Servant gives us a lot of information about what a server can do. We use this information to generate arbitrarily long request/response sessions and verify properties that should hold over them.

how?

In essence, fuzz @Api yourServer config will make a bunch of calls to your API, and record the results in a type-indexed dictionary. This means that they are now available for the prerequisites of other calls, so as you proceed, more and more api calls become possible.

We explicitly do not try to come up with plausible values that haven't somehow come back from the API. That's straying into QC/Hedgehog territory: if you want that, come up with the values on that side, and set them as seeds in the configuration.

what does it mean to be "available"?

In a simple API, you may make a call and get back a Foo, which will allow you to make another call that requires a Foo. In a more complicated app, it's likely that you'll send a request body that includes many subcomponents, and it's likely you'll get a response that needs to be broken down into pieces before it's useful.

To cope with this, we have the typeclasses BuildFrom and Breakdown. You can write instances for them if you feel like it, and indeed it's currently required for recursive datatypes if you don't want the fuzzer to hang, but for the majority of your types it should be sufficient to derive them generically. (Sensible instances are provided for lists.)

There are two basic strategies here. In some cases, you want to regard a type as indivisible: that's why we like newtypes, right? In this case, we can derive using the Atom strategy.

deriving via (Atom NewtypedKey) instance Breakdown NewtypedKey
deriving via (Atom NewtypedKey) instance BuildFrom NewtypedKey

This is saying "A can neither be built from components or broken down for spare parts. Hands off!". This is a good strategy for key types, for instance.

If instead it's a big complicated thing with lots of juicy subcomponents, we want to rip it apart using Generics and feast on its succulent headmeats:

deriving via (Compound Payload) instance Breakdown Payload
deriving via (Compound Payload) instance BuildFrom Payload

priming the pump

Sometimes there are values we'd like to smuggle into the API that are not derivable from within the API itself: sometimes this is a warning sign that your API is incomplete, but it can be quite reasonable to require identifying credentials within an API and not provide a way to get them. It might also be reasonable to have some sample values that the user is expected to come up with.

For those cases, override the seed in the Config with a list of seed values, suitably hashed:

defaultConfig { seed = [hashedDyn creds, hashedDyn userJwt]}

why not servant-quickcheck?

servant-quickcheck is a great package and I've learned a lot from it. Unfortunately, as mentioned previously, there's a lot of the state space you just can't explore without context: modern webapps are full of pointer-like structures, whether they're URLs or database keys/uuids, and servant-quickcheck requires that you be able to generate these without context via Arbitrary.

limitations and future work

Currently, the display of failing traces is pretty tragic, both in the formatting and in its non-minimality. This is pretty ticklish: arguably the right way to do this is to return a trace that we can also rerun, and let quickcheck or hedgehog a level up shrink it until it's satisfactorily short. In the interest of being useful earlier rather than later, I'm releasing v1.0 before I crack this particular nut. We do know which calls we made that led to the failing case, so we would want to show that distinction in a visible way: it's possible that other calls that don't have direct data dependencies were important, but we definitely know we need the direct data dependencies.

The provenance stuff is a bit underbaked. It should at least pull a representation of the route chosen rather than just an integer index.

It would also be nice to have a robust strategy for deriving recursive datatypes, or at least rejecting attempts to generate them that don't end in an infinite loop.

Currently the FlattenServer instance for :> is quadratic. It would be nice to fix this but I lack the art.