From 1f213253d33fca9aabb9a47674b40d995e9caee8 Mon Sep 17 00:00:00 2001
From: Carlana Johnson <mail@carlana.net>
Date: Mon, 23 Dec 2024 09:48:29 -0500
Subject: [PATCH] Docs: Clean up reqtest.Recorder docs a little

---
 reqtest/recorder.go              | 10 ++++-----
 reqtest/recorder_example_test.go | 35 +++++++++++++++++++++++---------
 2 files changed, 29 insertions(+), 16 deletions(-)

diff --git a/reqtest/recorder.go b/reqtest/recorder.go
index f89aa34..40b6512 100644
--- a/reqtest/recorder.go
+++ b/reqtest/recorder.go
@@ -2,8 +2,6 @@ package reqtest
 
 import (
 	"net/http"
-
-	"github.com/carlmjohnson/requests"
 )
 
 // RecorderMode is an argument type controlling [Recorder].
@@ -18,7 +16,7 @@ const (
 	// Replay responses from pre-recorded text files.
 	ModeReplay
 	// Replay responses from pre-recorded files if present,
-	// otherwise record a new request response pair.
+	// otherwise record a new request/response pair.
 	ModeCache
 )
 
@@ -26,9 +24,9 @@ const (
 // Requests and responses are read from or written to
 // text files in basepath according to a hash of their contents.
 // File names may optionally be prefixed with comments for better human organization.
-// The http.RoundTripper is only used in ModeRecord and ModeCache
-// and if nil defaults to http.DefaultTransport.
-func Recorder(mode RecorderMode, rt http.RoundTripper, basepath string) requests.Transport {
+// The http.RoundTripper is only used in [ModeRecord] and [ModeCache]
+// and if nil defaults to [http.DefaultTransport].
+func Recorder(mode RecorderMode, rt http.RoundTripper, basepath string) http.RoundTripper {
 	switch mode {
 	case ModeReplay:
 		return Replay(basepath)
diff --git a/reqtest/recorder_example_test.go b/reqtest/recorder_example_test.go
index 83f23b3..4d0b230 100644
--- a/reqtest/recorder_example_test.go
+++ b/reqtest/recorder_example_test.go
@@ -29,34 +29,49 @@ An example response.`
 	// true
 }
 
-func ExampleRecorder() {
+func copyToTempDir(m map[string]string) string {
 	dir, err := os.MkdirTemp("", "")
 	if err != nil {
 		panic(err)
 	}
-	err = os.CopyFS(dir, fstest.MapFS{
-		"fsys.example - MKIYDwjs.res.txt": &fstest.MapFile{
-			Data: []byte(`HTTP/1.1 200 OK
+	fsys := make(fstest.MapFS, len(m))
+	for path, content := range m {
+		fsys[path] = &fstest.MapFile{
+			Data: []byte(content),
+		}
+	}
+	if err = os.CopyFS(dir, fsys); err != nil {
+		panic(err)
+	}
+	return dir
+}
+
+func ExampleRecorder() {
+	// Given a directory with the following file
+	dir := copyToTempDir(map[string]string{
+		"fsys.example - MKIYDwjs.res.txt": `HTTP/1.1 200 OK
 Content-Type: text/plain; charset=UTF-8
 Date: Mon, 24 May 2021 18:48:50 GMT
 
-An example response.`),
-		},
+An example response.`,
 	})
-	if err != nil {
-		panic(err)
-	}
+	defer os.RemoveAll(dir)
+
+	// Make a test transport that reads the directory
+	tr := reqtest.Recorder(reqtest.ModeReplay, nil, dir)
 
+	// And test that it produces the correct response
 	var s string
 	const expected = `An example response.`
 	if err := requests.
 		URL("http://fsys.example").
-		Transport(reqtest.Recorder(reqtest.ModeReplay, nil, dir)).
+		Transport(tr).
 		ToString(&s).
 		Fetch(context.Background()); err != nil {
 		panic(err)
 	}
 	fmt.Println(s == expected)
+
 	// Output:
 	// true
 }