diff --git a/src/docs/markdown/advanced-testing.md b/src/docs/markdown/advanced-testing.md new file mode 100644 index 0000000..1d00d45 --- /dev/null +++ b/src/docs/markdown/advanced-testing.md @@ -0,0 +1,87 @@ +--- +title: Advanced testing for your caddy server +--- + +Advanced Testing of Servers +================= + +This guide deals with automated testing of your caddy configuration. This can helpful if you have complex routing logic or if you are building a caddy module and want a way to verify your code will run against a caddy server as part of your local development and CI/CD processes. + +## Testing using Go + +Caddy is written in Go, as are all of the plugins. Go also comes with built-in testing framework, we can leverage that to test our config and modules. + +Here is a complete example. + +This test will: + a) create a new tester + b) load the configuration against an in memory Caddy server + c) then make a test request against the server. + +```go +func TestRespond(t *testing.T) { + + // arrange + tester := caddytest.NewTester(t) + tester.InitServer(` + { + http_port 9080 + https_port 9443 + } + + localhost:9080 { + respond /version 200 { + body "hello from localhost" + } + } + `, "caddyfile") + + // act and assert + tester.AssertGetResponse("http://localhost:9080/version", 200, "hello from localhost") +} +``` + +As go users will know, you can run this test using this command (add `-v` for more details) + +```sh +go test ./... -run TestRespond +``` + + +## Testing against a live domain + +Often it would be nice to test your configuration using a live site. With tls. Caddy can do that too, it is a pretty neat trick. + +This test will: + a) create a new tester + b) load the configuration against an in memory Caddy server + c) generate local certificates via the SmallStep integration + d) make an request to https://www.eff.com which will be re-routed to the test server + +```go +func TestLiveRespond(t *testing.T) { + + // arrange + tester := caddytest.NewTester(t) + tester.InitServer(` + { + local_certs + } + + www.eff.org { + + respond /example 200 { + body "hello from the eff (well not really)" + } + } + `, "caddyfile") + + // act and assert + tester.AssertGetResponse("https://www.eff.org/example", 200, "hello from the eff (well not really)") +} +``` + +## Further documentation + +There are many more testing features, including support for `PUT`, `POST`, `PATCH`, `DELETE` are documented here [caddytest](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-test.4/caddytest?tab=doc) + diff --git a/src/docs/markdown/testing.md b/src/docs/markdown/testing.md new file mode 100644 index 0000000..d5fbdbe --- /dev/null +++ b/src/docs/markdown/testing.md @@ -0,0 +1,143 @@ +--- +title: How to test your caddy server +--- + +Testing Servers +================= + +Before releasing your web server to production you will want test it. Here is a quick guide to testing Caddy locally including support for HTTPS certificates. + +## Testing using CURL + +Lets start with a simple caddyfile. This will start a server on port `9080` which means it should run on your system without elevated permissions. + +```Caddyfile +http://localhost:9080 { + respond / 200 { + body "hello from caddy" + } +} +``` + +### Basic testing with curl + +The most basic testing you can do with curl is simply make a `Get` request. + +```sh +curl http://localhost:9080 + +> hello from caddy +``` + +For a little more information add `-i`. This becomes handy when testing things like `redirects`. + +```sh +curl -i http://localhost:9080 + +> HTTP/1.1 200 OK +> Server: Caddy +> Date: Sat, 04 Apr 2020 20:31:32 GMT +> Content-Length: 20 +> +> hello from localhost +``` + +#### Testing a redirect + +Lets update our server to include a redirect from an old page `moved` to a new one `overhere`. + +```Caddyfile +http://localhost:9080 { + + redir /moved /overhere 301 + + respond / 200 { + body "hello from caddy" + } + + respond /overhere 200 { + body "hello from over here" + } +} +``` + +Lets try curling the moved page and log the response. + +```sh +curl -i http://localhost:9080/moved + +> HTTP/1.1 301 Moved Permanently +> Location: /overhere +> Server: Caddy +> Date: Sat, 04 Apr 2020 20:46:15 GMT +> Content-Length: 0 +``` + +Note the `HTTP/1.1 301 Moved Permanently` is a different http status code and the `Location: /overhere`. Curl didn't actually follow the redirect like a webrowser would. + +To tell curl to act like a webbrowser requires another option `-L`. + +```sh +curl -i -L http://localhost:9080/moved + +> HTTP/1.1 301 Moved Permanently +> Location: /overhere +> Server: Caddy +> Date: Sat, 04 Apr 2020 20:51:00 GMT +> Content-Length: 0 + +> HTTP/1.1 200 OK +> Server: Caddy +> Date: Sat, 04 Apr 2020 20:51:00 GMT +> Content-Length: 20 + +> hello from over here +``` + +Note here that curl makes 2 requests, the first to the `/moved` page and then it follows the redirect to `/overhere` and finally returns the text `hello from over here`. + +### Basic testing with curl over TLS locally + +Caddy makes it super simple to create a webserver with HTTPS support. + +```Caddyfile +localhost { + respond / 200 { + body "hello from caddy" + } +} +``` + +Lets test using `https` + +```sh +curl -i https://localhost + +HTTP/2 200 +server: Caddy +content-length: 16 +date: Sat, 02 May 2020 07:21:48 GMT + +hello from caddy +``` + +Using the same Caddyfile above, lets test another "secure by default" feature, automatic http -> https redirection. + +```sh +curl -i http://localhost + +HTTP/1.1 308 Permanent Redirect +Connection: close +Location: https://localhost/ +Server: Caddy +Date: Sat, 02 May 2020 07:24:49 GMT +Content-Length: 0 +``` + +Notice that Caddy will assume that TLS is expected and create an automatic redirection to `Location: https://localhost/`. Cool huh. + + + + + + diff --git a/src/includes/docs-nav.html b/src/includes/docs-nav.html index 9d006b3..5fa4798 100644 --- a/src/includes/docs-nav.html +++ b/src/includes/docs-nav.html @@ -40,6 +40,8 @@