Document globalFlags and globalState

cmd/root.go

@@ -53,6 +53,7 @@ const (
 	waitRemoteLoggerTimeout = time.Second * 5
 )
 
+// globalFlags contains global config values that apply for all k6 sub-commands.
 type globalFlags struct {
 	configFilePath string
 	runType        string
@@ -64,6 +65,19 @@ type globalFlags struct {
 	verbose        bool
 }
 
+// globalState contains the globalFlags and accessors for most of the global
+// process-external like CLI arguments, env vars, standard input, output and
+// error, etc. In practice, most of it is normally accessed through the `os`
+// package from the Go stdlib.
+//
+// We group them here so we can prevent direct access to them from the rest of
+// the k6 codebase. This gives us the ability to mock them and have robust and
+// easy-to-write integration-like tests to check the k6 end-to-end behavior in
+// any simulated conditions.
+//
+// `newGlobalState()` returns a globalState object with the real `os`
+// parameters, while `newGlobalTestState()` can be used in tests to create
+// simulated environments.
 type globalState struct {
 	ctx context.Context