From 00585506c314cd3d784ceed4bd25eb6bde9e7662 Mon Sep 17 00:00:00 2001
From: Pengyuan Bian <bianpengyuan@google.com>
Date: Mon, 7 Dec 2020 12:13:11 -0800
Subject: [PATCH] Add comments to commonly used steps. (#3120)

---
 test/envoye2e/driver/check.go    |  1 +
 test/envoye2e/driver/envoy.go    |  3 +++
 test/envoye2e/driver/scenario.go | 32 ++++++++++++++++++++++++++++----
 test/envoye2e/driver/xds.go      |  2 ++
 4 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/test/envoye2e/driver/check.go b/test/envoye2e/driver/check.go
index 9eccb259339..33edd688073 100644
--- a/test/envoye2e/driver/check.go
+++ b/test/envoye2e/driver/check.go
@@ -29,6 +29,7 @@ const (
 	Any            = "*"
 )
 
+// HTTPCall sends a HTTP request to a localhost port, and then check the response code, and response headers.
 type HTTPCall struct {
 	// Method
 	Method string
diff --git a/test/envoye2e/driver/envoy.go b/test/envoye2e/driver/envoy.go
index f6c3558168e..9df2f79941e 100644
--- a/test/envoye2e/driver/envoy.go
+++ b/test/envoye2e/driver/envoy.go
@@ -39,6 +39,7 @@ import (
 	"istio.io/proxy/test/envoye2e/env"
 )
 
+// Envoy starts up a Envoy process locally.
 type Envoy struct {
 	// template for the bootstrap
 	Bootstrap string
@@ -60,6 +61,7 @@ type Envoy struct {
 
 var _ Step = &Envoy{}
 
+// Run starts a Envoy process.
 func (e *Envoy) Run(p *Params) error {
 	bootstrap, err := p.Fill(e.Bootstrap)
 	if err != nil {
@@ -128,6 +130,7 @@ func (e *Envoy) Run(p *Params) error {
 	return env.WaitForHTTPServer(url)
 }
 
+// Cleanup stops the Envoy process.
 func (e *Envoy) Cleanup() {
 	log.Printf("stop envoy ...\n")
 	defer os.Remove(e.tmpFile)
diff --git a/test/envoye2e/driver/scenario.go b/test/envoye2e/driver/scenario.go
index de2a0843c03..a1a48948480 100644
--- a/test/envoye2e/driver/scenario.go
+++ b/test/envoye2e/driver/scenario.go
@@ -33,37 +33,60 @@ import (
 )
 
 type (
+	// Params include test context that is shared by all steps.
 	Params struct {
+		// Config is the XDS server state.
 		Config XDSServer
-		Ports  *env.Ports
-		Vars   map[string]string
-		N      int
+
+		// Ports record the port assignment for a test.
+		Ports *env.Ports
+
+		// Vars include the variables which are used to fill in configuration template files.
+		Vars map[string]string
+
+		// N records the index of repetition. It is only valid when using with Repeat step.
+		N int
 	}
+
+	// Step is a unit of execution in the integration test.
 	Step interface {
+		// Run wraps the logic of a test step.
 		Run(*Params) error
+
+		// Cleanup cleans up all the test artifacts created by Run.
 		Cleanup()
 	}
+
+	// Scenario is a collection of Steps. It runs and cleans up all steps sequentially.
 	Scenario struct {
+		// Steps is a collection of steps which be executed sequentially.
 		Steps []Step
 	}
+
 	// Repeat a step either for N number or duration
 	Repeat struct {
 		N        int
 		Duration time.Duration
 		Step     Step
 	}
+
+	// Sleep injects a sleep with the given duration into the test execution.
 	Sleep struct {
 		time.Duration
 	}
+
 	// Fork will copy params to avoid concurrent access
 	Fork struct {
 		Fore Step
 		Back Step
 	}
-	// Lambda captured step
+
+	// StepFunction models Lambda captured step
 	StepFunction func(p *Params) error
 )
 
+// NewTestParams creates a new test params struct which keeps state of a test. vars will be used for template filling.
+// A set of ports will be assigned. If TestInventory is provided, the port assignment will be offsetted based on the index of the test in the inventory.
 func NewTestParams(t *testing.T, vars map[string]string, inv *env.TestInventory) *Params {
 	ind := inv.GetTestIndex(t)
 	ports := env.NewPorts(ind)
@@ -111,6 +134,7 @@ func (s *Sleep) Run(_ *Params) error {
 }
 func (s *Sleep) Cleanup() {}
 
+// Fill a template file with ariable map in Params.
 func (p *Params) Fill(s string) (string, error) {
 	t := template.Must(template.New("params").
 		Option("missingkey=zero").
diff --git a/test/envoye2e/driver/xds.go b/test/envoye2e/driver/xds.go
index ddff64d05aa..8b9916162ab 100644
--- a/test/envoye2e/driver/xds.go
+++ b/test/envoye2e/driver/xds.go
@@ -46,6 +46,7 @@ type XDSServer struct {
 
 var _ Step = &XDS{}
 
+// Run starts up an Envoy XDS server.
 func (x *XDS) Run(p *Params) error {
 	log.Printf("XDS server starting on %d\n", p.Ports.XDSPort)
 	x.grpc = grpc.NewServer()
@@ -65,6 +66,7 @@ func (x *XDS) Run(p *Params) error {
 	return nil
 }
 
+// Cleanup stops the XDS server.
 func (x *XDS) Cleanup() {
 	log.Println("stopping XDS server")
 	x.grpc.GracefulStop()