---
title: System tests for Hagrid
template: python
bindings:
- subplot.yaml
- lib/files.yaml
functions:
- subplot.py
- lib/files.py
...

# Introduction

This document documents the acceptance criteria for Hagrid, an OpenPGP
key server. The criteria are expressed against a system running
Hagrid, on its HTTP API. The [Subplot][] tool can be used to generate
code that verifies that a Hagrid system works as required.

[Subplot]: https://subplot.tech/


# VKS interface

## Lookup certificate by fingerprint

### We can look up an existing certificate

_Requirement: We can retrieve a certificate whose fingerprint we
have._

FIXME: a well-known test cert must be injected into the running Hagrid
instance prior to the test, and `EXAMPLEFP` must be replaced with its
fingerprint.

~~~scenario
given a running Hagrid system
given file well-known.pgp
when I make request GET /vks/v1/by-fingerprint/EXAMPLEFP
then response HTTP status code is 200
then response has header content-type: application/octet-stream
then response body matches file well-known.pgp
~~~

~~~{#well-known.pgp .file}
certificate
~~~

### We get an error if using lower case hexadecimal

_Requirement: we get an error if we use a fingerprint with lowercase
hexadecimal digits._

~~~scenario
given a running Hagrid system
when I make request GET /vks/v1/by-fingerprint/EXAMPLEFP
then response HTTP status code is 400
~~~

### We get an error for a malformed fingerprint

_Requirement: we get an error if we try to retrieve a certificate
using a string that is not a syntactically valid fingerprint._

~~~scenario
given a running Hagrid system
when I make request GET /vks/v1/by-fingerprint/IMPOSSIBLE
then response HTTP status code is 400
~~~

### We get an error for a missing fingerprint

_Requirement: we get an error if we try to retrieve a certificate
that isn't on the server._

~~~scenario
given a running Hagrid system
when I make request GET /vks/v1/by-fingerprint/010203
then response HTTP status code is 400
~~~