Clarify documentation on (unit-)tests

[mdegel]

Feature Overview

At the moment the documentation in README.md only references the pebble tests.

However the Makefile also contains a section for running unittest for tests defined e.g. in

nginx-acme/src/acme/types.rs

Lines 384 to 527 in 1cb00ec

	#[cfg(test)]
	mod tests {
	use super::*;
	#[test]
	fn order() {
	let _order: Order = serde_json::from_str(
	r#"{
	"status": "valid",
	"expires": "2016-01-20T14:09:07.99Z",
	"identifiers": [
	{ "type": "dns", "value": "www.example.org" },
	{ "type": "dns", "value": "example.org" }
	],
	"notBefore": "2016-01-01T00:00:00Z",
	"notAfter": "2016-01-08T00:00:00Z",
	"authorizations": [
	"https://example.com/acme/authz/PAniVnsZcis",
	"https://example.com/acme/authz/r4HqLzrSrpI"
	],
	"finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize",
	"certificate": "https://example.com/acme/cert/mAt3xBGaobw"
	}"#,
	)
	.unwrap();
	}
	#[test]
	fn authorization() {
	let auth: Authorization = serde_json::from_str(
	r#"
	{
	"status": "pending",
	"identifier": {
	"type": "dns",
	"value": "www.example.org"
	},
	"challenges": [
	{
	"type": "http-01",
	"url": "https://example.com/acme/chall/prV_B7yEyA4",
	"status": "pending",
	"token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0"
	},
	{
	"type": "dns-01",
	"url": "https://example.com/acme/chall/Rg5dV14Gh1Q",
	"status": "pending",
	"token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"
	},
	{
	"type": "tls-alpn-01",
	"url": "https://example.com/acme/chall/TJds3qqnMAf",
	"status": "pending",
	"token": "nRsTyUVQh1YAwovxwzAEVgtFLRV47f7HAcRfl6pED5Y="
	}
	],
	"wildcard": false
	}"#,
	)
	.unwrap();
	assert_eq!(auth.challenges.len(), 3);
	assert_eq!(auth.challenges[0].kind, ChallengeKind::Http01);
	assert_eq!(auth.challenges[1].kind, ChallengeKind::Dns01);
	assert_eq!(auth.challenges[2].kind, ChallengeKind::TlsAlpn01);
	}
	#[test]
	fn error_kind() {
	let err: Problem = serde_json::from_str(
	r#"
	{
	"type": "urn:ietf:params:acme:error:badNonce",
	"detail": "The client sent an unacceptable anti-replay nonce"
	}"#,
	)
	.unwrap();
	assert_eq!(err.kind, ErrorKind::BadNonce);
	let err: Problem = serde_json::from_str(
	r#"
	{
	"type": "urn:ietf:params:acme:error:caa",
	"detail": "CAA records forbid the CA from issuing a certificate"
	}"#,
	)
	.unwrap();
	assert_eq!(err.kind, ErrorKind::Caa);
	let err: Problem = serde_json::from_str(
	r#"
	{
	"type": "unknown-error",
	"detail": "Some unknown error"
	}"#,
	)
	.unwrap();
	assert_eq!(err.kind, ErrorKind::Other("unknown-error".to_string()));
	let err: Problem = serde_json::from_str(
	r#"
	{
	"type": "urn:ietf:params:acme:error:malformed",
	"detail": "Some of the identifiers requested were rejected",
	"subproblems": [
	{
	"type": "urn:ietf:params:acme:error:malformed",
	"detail": "Invalid underscore in DNS name \"_example.org\"",
	"identifier": {
	"type": "dns",
	"value": "_example.org"
	}
	},
	{
	"type": "urn:ietf:params:acme:error:rejectedIdentifier",
	"detail": "This CA will not issue for \"example.net\"",
	"identifier": {
	"type": "dns",
	"value": "example.net"
	}
	}
	]
	}"#,
	)
	.unwrap();
	assert_eq!(err.kind, ErrorKind::Malformed);
	assert_eq!(err.subproblems.len(), 2);
	assert_eq!(
	err.subproblems[0].identifier,
	Some(Identifier::Dns("_example.org".to_string()))
	)
	}
	}

These tests should be Rust only, yet fail to run with either make unittest, or cargo test:

$ make unittest
NGINX_SOURCE_DIR="/home/user/git/nginx-acme/nginx" NGINX_BUILD_DIR="/home/user/git/nginx-acme/objs-debug" cargo test
   Compiling nginx-acme v0.2.0 (/home/user/git/nginx-acme)
error: linking with `cc` failed: exit status: 1
# ...
  = note: some arguments are omitted. use `--verbose` to show all linker arguments
  = note: rust-lld: error: undefined symbol: ngx_conf_merge_path_value
          >>> referenced by issuer.rs:153 (src/conf/issuer.rs:153)
          >>>               /home/user/git/nginx-acme/target/debug/deps/nginx_acme-9f00e46ff2f66d37.0iaggq6qx2mdlowjfuob5l9m2.0afbhqs.rcgu.o:(nginx_acme::conf::issuer::Issuer::init::h697e11fb3198fec8)

These tests seemingly are also not run during CI, nor are they part of the overall make test or make full-test.

It should be clarified if these tests are intended to be run and if so, what the correct procedure for it is.

Alternatives Considered

• Remove unit tests if not intended to run at all.
• Provide proper instructions for building them with correct linking (probably a lot of unnecessary overhead).
• Extract the ACME logic and other pure-Rust components into a small “core” crate with no nginx dependencies, that can be tested independently.

Additional Context

No response