Merge pull request #47 from go-spectest/add-documentation-comment

Add documentation comment

CHANGELOG.md

@@ -4,9 +4,12 @@
 ### Changed
 - Dependabot update go.mod in example codes.
 
+### Removed
+- `SpecTest.RecorderHook` is deprecated since apitest package era.
+
 ## [0.0.3] - 2023-10-09
 ### Added
-- supprt more http methods; HEAD, OPTIONS, CONNECT, TRACE
+- support more http methods; HEAD, OPTIONS, CONNECT, TRACE
 
 ### Fixed
 - Broken example codes. However, some examples are still broken (iris, qraphql).
@@ -44,4 +47,4 @@
 
 ### Removed
 - `APITest.Meta()` method.
-  - The precise information of the meta (map[string]interface{}) was not being exposed to users. Consequently, users found it challenging to effectively utilize APITest.Meta(). Instead of providing an alternative method, APITest.Meta() was removed.
+  - The precise information of the meta (map[string]interface{}) was not being exposed to users. Consequently, users found it challenging to effectively utilize APITest.Meta(). Instead of providing an alternative method, APITest.Meta() was removed.

assert.go

@@ -21,14 +21,18 @@ type Assert func(*http.Response, *http.Request) error
 // TestingT is an interface to wrap the native *testing.T interface, this allows integration with GinkgoT() interface
 // GinkgoT interface defined in https://github.com/onsi/ginkgo/blob/55c858784e51c26077949c81b6defb6b97b76944/ginkgo_dsl.go#L91
 type TestingT interface {
+	// Errorf is equivalent to Log followed by Fail
 	Errorf(format string, args ...interface{})
+	// Fatal is equivalent to Log followed by FailNow
 	Fatal(args ...interface{})
+	// Fatalf is equivalent to Log followed by FailNow
 	Fatalf(format string, args ...interface{})
 }
 
 // failureMessageArgs are passed to the verifier but get stripped out from the user facing error message that gets printed
 // it allows the test to pass additional info about the failure such as the test name.
 type failureMessageArgs struct {
+	// Name is the name of the test. It's is `SpecTest.name``
 	Name string
 }
 

spectest.code-workspace

@@ -17,6 +17,7 @@
             "bestsize",
             "bodyclose",
             "Bodyf",
+            "Connectf",
             "davecgh",
             "deadcode",
             "Deletef",
@@ -30,12 +31,16 @@
             "fromfiledate",
             "fsadg",
             "Getf",
+            "gocritic",
+            "golangci",
             "gomod",
             "gosimple",
             "govet",
             "Headerkey",
+            "Headf",
             "hljs",
             "ineffassign",
+            "ioutil",
             "kddejong",
             "kfiufhtne",
             "lineterm",
@@ -47,19 +52,23 @@
             "octocov",
             "onclick",
             "onscroll",
+            "Optionsf",
             "Patchf",
             "pdsanjdna",
             "plantuml",
             "Postf",
             "Putf",
             "qabxcd",
+            "qraphql",
             "Ratcliff",
             "readlines",
+            "reviewdog",
             "Sdump",
             "Seqs",
             "shellcheck",
             "spectest",
             "steinfletcher",
+            "struct",
             "structcheck",
             "stylesheet",
             "tbody",
@@ -68,6 +77,7 @@
             "todos",
             "tofile",
             "tofiledate",
+            "Tracef",
             "typecheck",
             "unidiff",
             "varcheck",

spectest.go

@@ -1,4 +1,5 @@
-// Package spectest is simple and extensible behavioral testing library for Go. You can use api test to simplify REST API, HTTP handler and e2e tests. (forked from steinfletcher/apitest)
+// Package spectest is simple and extensible behavioral testing library for Go. You can use api test to simplify REST API,
+// HTTP handler and e2e tests. (forked from steinfletcher/apitest)
 package spectest
 
 import (
@@ -28,21 +29,33 @@ type SpecTest struct {
 	networkingHTTPClient *http.Client
 	// reporter is the report formatter.
 	reporter ReportFormatter
-	// verifier is the assertion implementation
-	verifier       Verifier
-	recorder       *Recorder
-	handler        http.Handler
-	name           string
-	request        *Request
-	response       *Response
-	observers      []Observe
+	// verifier is the assertion implementation. Default is DefaultVerifier.
+	verifier Verifier
+	// recorder is the test result recorder.
+	recorder *Recorder
+	// handler is the http handler that is invoked when the test is run
+	handler http.Handler
+	// name is the name of the test. It will appear in the test report as sub title.
+	name string
+	// request is the request spec. It is called by the test runner to build the request.
+	request *Request
+	// response is the expected response. It is called by the test runner to assert the response.
+	response *Response
+	// observers is a list of functions that will be called on completion of the test.
+	// It is used to capture the inbound request and final response.
+	observers []Observe
+	// mocksObservers is a list of functions that will be called on completion of the test.
+	// It is used to capture the mock request and response.
 	mocksObservers []Observe
-	recorderHook   RecorderHook
-	mocks          []*Mock
-	t              TestingT
-	httpClient     *http.Client
-	httpRequest    *http.Request
-	transport      *Transport
+	// mocks is a list of mocks that will be used to intercept the request.
+	mocks []*Mock
+	// t is the testing.T instance.
+	t TestingT
+	// httpClient is the http client used when networking is enabled
+	httpClient *http.Client
+	// httpRequest is the native `http.Request`
+	httpRequest *http.Request
+	transport   *Transport
 	// meta is the meta data for the test report.
 	meta     *Meta
 	started  time.Time
@@ -52,9 +65,6 @@ type SpecTest struct {
 // Observe will be called by with the request and response on completion
 type Observe func(*http.Response, *http.Request, *SpecTest)
 
-// RecorderHook used to implement a custom interaction recorder
-type RecorderHook func(*Recorder)
-
 // New creates a new api test. The name is optional and will appear in test reports
 func New(name ...string) *SpecTest {
 	apiTest := &SpecTest{
@@ -186,14 +196,6 @@ func (s *SpecTest) ObserveMocks(observer Observe) *SpecTest {
 	return s
 }
 
-// RecorderHook allows the consumer to provider a function that will receive the recorder instance before the
-// test runs. This can be used to inject custom events which can then be rendered in diagrams
-// Deprecated: use Recorder() instead
-func (s *SpecTest) RecorderHook(hook RecorderHook) *SpecTest {
-	s.recorderHook = hook
-	return s
-}
-
 // Request returns the request spec
 func (s *SpecTest) Request() *Request {
 	return s.request
@@ -371,10 +373,6 @@ func (s *SpecTest) report() *http.Response {
 	}
 	defer s.recorder.Reset()
 
-	if s.recorderHook != nil {
-		s.recorderHook(s.recorder)
-	}
-
 	s.started = time.Now()
 	res := s.response.runTest()
 	s.finished = time.Now()