Add support for STDOUT/STDERR expectations for Exec checker

this change adds stdout/stderr capturing to the Exec checker
in order to verify the collected data against a regular expression.

unit tests have been implemented to verify the implementation.

closes #431

Author: UiP9AV6Y

README.md

@@ -401,6 +401,14 @@ Wait for a shell command to succeed or return a specific exit code.
   ```bash
   wait4x exec 'ls target/debug/main' --exit-code 2
   ```
+- **Check docker container status:**
+  ```bash
+  wait4x exec 'docker inspect -f {{.State.Running}} my_container_name' --expect-stdout-regex "true"
+  ```
+- **Check lockfile is absent:**
+  ```bash
+  wait4x exec 'ls /run/daemon/init.lock' --exit-code 2 --expect-stderr-regex "No such file or directory"
+  ```
 
 ---
 

checker/exec/exec.go

@@ -20,6 +20,7 @@ import (
 	"fmt"
 	"os/exec"
 	"strings"
+	"sync"
 
 	"wait4x.dev/v3/checker"
 )
@@ -29,9 +30,11 @@ type Option func(e *Exec)
 
 // Exec is a command execution checker
 type Exec struct {
-	command        string
-	args           []string
-	expectExitCode int
+	command           string
+	args              []string
+	expectExitCode    int
+	expectStdoutRegex string
+	expectStderrRegex string
 }
 
 // New creates a new Exec checker
@@ -63,6 +66,22 @@ func WithExpectExitCode(code int) Option {
 	}
 }
 
+// WithExpectStdoutRegex configures the regular expression
+// which is evaluated against STDOUT.
+func WithExpectStdoutRegex(pattern string) Option {
+	return func(e *Exec) {
+		e.expectStdoutRegex = pattern
+	}
+}
+
+// WithExpectStderrRegex configures the regular expression
+// which is evaluated against STDERR.
+func WithExpectStderrRegex(pattern string) Option {
+	return func(e *Exec) {
+		e.expectStderrRegex = pattern
+	}
+}
+
 // Identity returns the identity of the checker
 func (e *Exec) Identity() (string, error) {
 	if len(e.args) > 0 {
@@ -73,9 +92,60 @@ func (e *Exec) Identity() (string, error) {
 
 // Check executes the command and checks if it returns the expected exit code
 func (e *Exec) Check(ctx context.Context) error {
+	var stdout, stderr *pipeProcessor
+	var errs chan error
+	var err error
+
 	// Create command with context for cancellation support
 	cmd := exec.CommandContext(ctx, e.command, e.args...)
-	err := cmd.Run()
+
+	stdout, err = newPipeProcessor(e.expectStdoutRegex, cmd.StdoutPipe)
+	if err != nil {
+		return checker.NewExpectedError(
+			"failed to prepare STDOUT processor", err,
+			"command", e.command,
+			"args", e.args,
+		)
+	}
+
+	stderr, err = newPipeProcessor(e.expectStderrRegex, cmd.StderrPipe)
+	if err != nil {
+		return checker.NewExpectedError(
+			"failed to prepare STDERR processor", err,
+			"command", e.command,
+			"args", e.args,
+		)
+	}
+
+	if err := cmd.Start(); err != nil {
+		return checker.NewExpectedError(
+			"unable to start command", err,
+			"command", e.command,
+			"args", e.args,
+		)
+	}
+
+	if stdout != nil || stderr != nil {
+		var wg sync.WaitGroup
+		errs = make(chan error)
+
+		go func() {
+			// wait for the workers to finish processing all of the data
+			// before closing the channel, otherwise they will be blocked
+			wg.Wait()
+			close(errs)
+		}()
+
+		if stdout != nil {
+			stdout.Process(&wg, errs)
+		}
+
+		if stderr != nil {
+			stderr.Process(&wg, errs)
+		}
+	}
+
+	err = cmd.Wait()
 
 	// Check if context was canceled
 	select {
@@ -112,5 +182,22 @@ func (e *Exec) Check(ctx context.Context) error {
 		)
 	}
 
-	return nil
+	return drainErrors(errs)
+}
+
+// drainErrors reads all items from the given channel
+// and returns the last non-nil value or nil if the
+// channel is nil or does not contain any errors.
+func drainErrors(errs chan error) (err error) {
+	if errs == nil {
+		return
+	}
+
+	for e := range errs {
+		if e != nil {
+			err = e
+		}
+	}
+
+	return
 }

checker/exec/exec_test.go

@@ -0,0 +1,97 @@
+// Copyright 2019-2025 The Wait4X Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package exec provides the Exec checker for the Wait4X application.
+package exec
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestCheck tests the Exec checker against various test scenarios.
+func TestCheck(t *testing.T) {
+	const runner = "testdata/exec/runner.sh"
+
+	tests := map[string]struct {
+		haveOptions []Option
+		wantErr     string
+	}{
+		"minimal": {},
+		"unexpected exit code": {
+			haveOptions: []Option{
+				WithArgs([]string{"124"}), // instruct the runner to exit with code 124
+			},
+			wantErr: "command exited with unexpected code",
+		},
+		"expected exit code": {
+			haveOptions: []Option{
+				WithArgs([]string{"1"}),
+				WithExpectExitCode(1),
+			},
+		},
+		"stdout match": {
+			haveOptions: []Option{
+				WithExpectStdoutRegex("second line of stdout"),
+			},
+		},
+		"stdout mismatch": {
+			haveOptions: []Option{
+				WithExpectStdoutRegex("stderr"),
+			},
+			wantErr: "no matching line found",
+		},
+		"stderr match": {
+			haveOptions: []Option{
+				WithExpectStderrRegex("second line of stderr"),
+			},
+		},
+		"stderr mismatch": {
+			haveOptions: []Option{
+				WithExpectStderrRegex("stdout"),
+			},
+			wantErr: "no matching line found",
+		},
+		"both match": {
+			haveOptions: []Option{
+				WithExpectStdoutRegex("second line of stdout"),
+				WithExpectStderrRegex("second line of stderr"),
+			},
+		},
+		"both mismatch": {
+			haveOptions: []Option{
+				WithExpectStdoutRegex("stderr"),
+				WithExpectStderrRegex("stdout"),
+			},
+			wantErr: "no matching line found",
+		},
+	}
+
+	for name, test := range tests {
+		scenario := func(t *testing.T) {
+			subject := New(runner, test.haveOptions...)
+			gotErr := subject.Check(context.TODO())
+
+			if test.wantErr == "" {
+				assert.Nil(t, gotErr)
+			} else {
+				assert.ErrorContains(t, gotErr, test.wantErr)
+			}
+		}
+
+		t.Run(name, scenario)
+	}
+}

checker/exec/processor.go

@@ -0,0 +1,83 @@
+// Copyright 2019-2025 The Wait4X Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package exec provides the Exec checker for the Wait4X application.
+package exec
+
+import (
+	"bufio"
+	"io"
+	"regexp"
+	"sync"
+
+	"wait4x.dev/v3/checker"
+)
+
+type pipeProcessor struct {
+	reader  io.Reader
+	pattern *regexp.Regexp
+}
+
+func newPipeProcessor(pattern string, provider func() (io.ReadCloser, error)) (*pipeProcessor, error) {
+	if pattern == "" {
+		return nil, nil
+	}
+
+	reg, err := regexp.Compile(pattern)
+	if err != nil {
+		return nil, err
+	}
+
+	rdr, err := provider()
+	if err != nil {
+		return nil, err
+	}
+
+	result := &pipeProcessor{
+		reader:  rdr,
+		pattern: reg,
+	}
+
+	return result, nil
+}
+
+func (p *pipeProcessor) Process(wg *sync.WaitGroup, result chan<- error) {
+	process := bufio.NewScanner(p.reader)
+	worker := func(scanner *bufio.Scanner, pattern *regexp.Regexp) {
+		defer wg.Done()
+
+		match := false
+		for scanner.Scan() {
+			if !match && pattern.Match(scanner.Bytes()) {
+				match = true
+			}
+		}
+
+		if err := scanner.Err(); err != nil {
+			result <- checker.NewExpectedError(
+				"output scanner failed to process data", err,
+			)
+		}
+
+		if !match {
+			result <- checker.NewExpectedError(
+				"no matching line found", nil,
+				"regexp", pattern.String(),
+			)
+		}
+	}
+
+	wg.Add(1)
+	go worker(process, p.pattern)
+}

checker/exec/testdata/exec/runner.sh

@@ -0,0 +1,17 @@
+#!/bin/sh -eu
+
+cat <<STDOUT
+this is the first line of stdout
+this is the second line of stdout
+this is the third line of stdout
+this is the fourth line of stdout
+STDOUT
+
+cat <<STDERR >&2
+this is the first line of stderr
+this is the second line of stderr
+this is the third line of stderr
+this is the fourth line of stderr
+STDERR
+
+exit "${1:-0}"

internal/cmd/exec.go

@@ -52,13 +52,17 @@ func NewExecCommand() *cobra.Command {
 	}
 
 	execCommand.Flags().Int("exit-code", 0, "Expected exit code from the command")
+	execCommand.Flags().String("expect-stdout-regex", "", "Expect command STDOUT pattern.")
+	execCommand.Flags().String("expect-stderr-regex", "", "Expect command STDERR pattern.")
 
 	return execCommand
 }
 
 // runExec runs the exec command
 func runExec(cmd *cobra.Command, args []string) error {
 	exitCode, _ := cmd.Flags().GetInt("exit-code")
+	expectStdoutRegex, _ := cmd.Flags().GetString("expect-stdout-regex")
+	expectStderrRegex, _ := cmd.Flags().GetString("expect-stderr-regex")
 
 	logger, err := logr.FromContext(cmd.Context())
 	if err != nil {
@@ -90,6 +94,8 @@ func runExec(cmd *cobra.Command, args []string) error {
 	checker := exec.New(command,
 		exec.WithArgs(commandArgs),
 		exec.WithExpectExitCode(exitCode),
+		exec.WithExpectStdoutRegex(expectStdoutRegex),
+		exec.WithExpectStderrRegex(expectStderrRegex),
 	)
 
 	return waiter.WaitContext(