Add doc blocks for testcontainer helpers

sudorandom · Oct 13, 2024 · 2babb20 · 2babb20
1 parent b3f7db5
commit 2babb20
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 101 deletions.
diff --git a/example/testcontainers/main.go b/example/testcontainers/main.go
diff --git a/testcontainers/testcontainers.go b/testcontainers/testcontainers.go
@@ -22,6 +22,9 @@ type FauxRPCContainer struct {
 	testcontainers.Container
 }
 
+// Run will start the testcontainers. You can pass in your own image name. It's advisable to avoid using
+// the latest tag but if you want to, you would use "docker.io/sudorandom/fauxrpc:latest"
+// See here for all available versions: https://hub.docker.com/r/sudorandom/fauxrpc
 func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*FauxRPCContainer, error) {
 	container, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
 		ContainerRequest: testcontainers.ContainerRequest{
@@ -40,6 +43,7 @@ func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustom
 	}, nil
 }
 
+// MustBaseURL returns the base URL for the FauxRPC service. A panic happens if anything fails.
 func (c *FauxRPCContainer) MustBaseURL(ctx context.Context) string {
 	baseURL, err := c.BaseURL(ctx)
 	if err != nil {
@@ -48,6 +52,7 @@ func (c *FauxRPCContainer) MustBaseURL(ctx context.Context) string {
 	return baseURL
 }
 
+// BaseURL returns the base URL for the FauxRPC service. This will include a "http://" prefix.
 func (c *FauxRPCContainer) BaseURL(ctx context.Context) (string, error) {
 	endpoint, err := c.PortEndpoint(ctx, "6660/tcp", "http")
 	if err != nil {
@@ -56,10 +61,12 @@ func (c *FauxRPCContainer) BaseURL(ctx context.Context) (string, error) {
 	return endpoint, nil
 }
 
+// MustRegistryClient returns a client for managing types in the FauxRPC registry. A panic happens if anything fails.
 func (c *FauxRPCContainer) MustRegistryClient(ctx context.Context) registryv1connect.RegistryServiceClient {
 	return registryv1connect.NewRegistryServiceClient(http.DefaultClient, c.MustBaseURL(ctx))
 }
 
+// MustRegistryClient returns a client for managing types in the FauxRPC registry.
 func (c *FauxRPCContainer) RegistryClient(ctx context.Context) (registryv1connect.RegistryServiceClient, error) {
 	baseURL, err := c.BaseURL(ctx)
 	if err != nil {
@@ -68,12 +75,14 @@ func (c *FauxRPCContainer) RegistryClient(ctx context.Context) (registryv1connec
 	return registryv1connect.NewRegistryServiceClient(http.DefaultClient, baseURL), nil
 }
 
+// MustAddFileDescriptor adds the given file descriptor to the FauxRPC registry. A panic happens if anything fails.
 func (c *FauxRPCContainer) MustAddFileDescriptor(ctx context.Context, fd protoreflect.FileDescriptor) {
 	if err := c.AddFileDescriptor(ctx, fd); err != nil {
 		panic(err)
 	}
 }
 
+// MustAddFileDescriptor adds the given file descriptor to the FauxRPC registry.
 func (c *FauxRPCContainer) AddFileDescriptor(ctx context.Context, fd protoreflect.FileDescriptor) error {
 	client, err := c.RegistryClient(ctx)
 	if err != nil {
@@ -89,12 +98,14 @@ func (c *FauxRPCContainer) AddFileDescriptor(ctx context.Context, fd protoreflec
 	return err
 }
 
+// MustResetRegistry resets the FauxRPC registry to an empty state. A panic happens if anything fails.
 func (c *FauxRPCContainer) MustResetRegistry(ctx context.Context) {
 	if err := c.ResetRegistry(ctx); err != nil {
 		panic(err)
 	}
 }
 
+// ResetRegistry resets the FauxRPC registry to an empty state.
 func (c *FauxRPCContainer) ResetRegistry(ctx context.Context) error {
 	client, err := c.RegistryClient(ctx)
 	if err != nil {
@@ -104,10 +115,12 @@ func (c *FauxRPCContainer) ResetRegistry(ctx context.Context) error {
 	return err
 }
 
+// MustStubsClient returns a client for managing stubs in the FauxRPC registry. A panic happens if anything fails.
 func (c *FauxRPCContainer) MustStubsClient(ctx context.Context) stubsv1connect.StubsServiceClient {
 	return stubsv1connect.NewStubsServiceClient(http.DefaultClient, c.MustBaseURL(ctx))
 }
 
+// MustStubsClient returns a client for managing stubs in the FauxRPC registry.
 func (c *FauxRPCContainer) StubsClient(ctx context.Context) (stubsv1connect.StubsServiceClient, error) {
 	baseURL, err := c.BaseURL(ctx)
 	if err != nil {
@@ -116,12 +129,19 @@ func (c *FauxRPCContainer) StubsClient(ctx context.Context) (stubsv1connect.Stub
 	return stubsv1connect.NewStubsServiceClient(http.DefaultClient, baseURL), nil
 }
 
+// MustAddStub adds a stub to the FauxRPC stub database. A panic happens if anything fails.
 func (c *FauxRPCContainer) MustAddStub(ctx context.Context, target string, msg proto.Message) {
 	if err := c.AddStub(ctx, target, msg); err != nil {
 		panic(err)
 	}
 }
 
+// AddStub adds a stub to the FauxRPC stub database. Target is the full protobuf path to the type or service method.
+//
+// Examples:
+//
+//	err := AddStub(ctx, "connectrpc.eliza.v1.SayResponse", &elizav1.SayResponse{Sentence: "example"}
+//	err := AddStub(ctx, "connectrpc.eliza.v1.ElizaService/Say", &elizav1.SayResponse{Sentence: "example"}
 func (c *FauxRPCContainer) AddStub(ctx context.Context, target string, msg proto.Message) error {
 	client, err := c.StubsClient(ctx)
 	if err != nil {
@@ -145,12 +165,14 @@ func (c *FauxRPCContainer) AddStub(ctx context.Context, target string, msg proto
 	return err
 }
 
+// MustResetStubs resets the FauxRPC stub database to an empty state. A panic happens if anything fails.
 func (c *FauxRPCContainer) MustResetStubs(ctx context.Context) {
 	if err := c.ResetStubs(ctx); err != nil {
 		panic(err)
 	}
 }
 
+// MustResetStubs resets the FauxRPC stub database to an empty state.
 func (c *FauxRPCContainer) ResetStubs(ctx context.Context) error {
 	client, err := c.StubsClient(ctx)
 	if err != nil {