Allow to dump documents resulting of system tests (#2059)

Setting `ELASTIC_PACKAGE_TEST_DUMP_SCENARIO_DOCS` dumps
documents generated by system tests into a file in the temporary directory.

README.md

@@ -695,6 +695,9 @@ There are available some environment variables that could be used to change some
     - `ELASTIC_PACKAGE_DISABLE_ELASTIC_AGENT_WOLFI`: If set to `true`, the Elastic Agent image used for running agents will be using the Ubuntu docker images
       (e.g. `docker.elastic.co/elastic-agent/elastic-agent-complete`). If set to `false`, the Elastic Agent image used for the running agents will be based on the wolfi
       images (e.g. `docker.elastic.co/elastic-agent/elastic-agent-wolfi`). Default: `false`.
+    - `ELASTIC_PACKAGE_TEST_DUMP_SCENARIO_DOCS. If the variable is set, elastic-package will dump to a file the documents generated
+      by system tests before they are verified. This is useful to know exactly what fields are being verified when investigating
+      issues on this step. Documents are dumped to a file in the system temporary directory. It is disabled by default.
 
 - To configure the Elastic stack to be used by `elastic-package`:
     - `ELASTIC_PACKAGE_ELASTICSEARCH_HOST`: Host of the elasticsearch (e.g. https://127.0.0.1:9200)

internal/testrunner/runners/system/tester.go

@@ -123,7 +123,8 @@ var (
 			},
 		},
 	}
-	enableIndependentAgents = environment.WithElasticPackagePrefix("TEST_ENABLE_INDEPENDENT_AGENT")
+	enableIndependentAgentsEnv = environment.WithElasticPackagePrefix("TEST_ENABLE_INDEPENDENT_AGENT")
+	dumpScenarioDocsEnv        = environment.WithElasticPackagePrefix("TEST_DUMP_SCENARIO_DOCS")
 )
 
 type tester struct {
@@ -257,7 +258,7 @@ func NewSystemTester(options SystemTesterOptions) (*tester, error) {
 
 	// If the environment variable is present, it always has preference over the root
 	// privileges value (if any) defined in the manifest file
-	v, ok := os.LookupEnv(enableIndependentAgents)
+	v, ok := os.LookupEnv(enableIndependentAgentsEnv)
 	if ok {
 		r.runIndependentElasticAgent = strings.ToLower(v) == "true"
 	}
@@ -1528,9 +1529,36 @@ func (r *tester) runTest(ctx context.Context, config *testConfig, svcInfo servic
 		return result.WithError(err)
 	}
 
+	if dump, ok := os.LookupEnv(dumpScenarioDocsEnv); ok && dump != "" {
+		err := dumpScenarioDocs(scenario.docs)
+		if err != nil {
+			return nil, fmt.Errorf("failed to dump scenario docs: %w", err)
+		}
+	}
+
 	return r.validateTestScenario(ctx, result, scenario, config)
 }
 
+func dumpScenarioDocs(docs any) error {
+	timestamp := time.Now().Format("20060102150405")
+	path := filepath.Join(os.TempDir(), fmt.Sprintf("elastic-package-test-docs-dump-%s.json", timestamp))
+	f, err := os.Create(path)
+	if err != nil {
+		return fmt.Errorf("failed to create dump file: %w", err)
+	}
+	defer f.Close()
+
+	logger.Infof("Dumping scenario documents to %s", path)
+
+	enc := json.NewEncoder(f)
+	enc.SetIndent("", "  ")
+	enc.SetEscapeHTML(false)
+	if err := enc.Encode(docs); err != nil {
+		return fmt.Errorf("failed to encode docs: %w", err)
+	}
+	return nil
+}
+
 func checkEnrolledAgents(ctx context.Context, client *kibana.Client, agentInfo agentdeployer.AgentInfo, svcInfo servicedeployer.ServiceInfo, runIndependentElasticAgent bool) ([]kibana.Agent, error) {
 	var agents []kibana.Agent
 

tools/readme/readme.md.tmpl

@@ -237,6 +237,9 @@ There are available some environment variables that could be used to change some
     - `ELASTIC_PACKAGE_DISABLE_ELASTIC_AGENT_WOLFI`: If set to `true`, the Elastic Agent image used for running agents will be using the Ubuntu docker images
       (e.g. `docker.elastic.co/elastic-agent/elastic-agent-complete`). If set to `false`, the Elastic Agent image used for the running agents will be based on the wolfi
       images (e.g. `docker.elastic.co/elastic-agent/elastic-agent-wolfi`). Default: `false`.
+    - `ELASTIC_PACKAGE_TEST_DUMP_SCENARIO_DOCS. If the variable is set, elastic-package will dump to a file the documents generated
+      by system tests before they are verified. This is useful to know exactly what fields are being verified when investigating
+      issues on this step. Documents are dumped to a file in the system temporary directory. It is disabled by default.
 
 - To configure the Elastic stack to be used by `elastic-package`:
     - `ELASTIC_PACKAGE_ELASTICSEARCH_HOST`: Host of the elasticsearch (e.g. https://127.0.0.1:9200)