feat(f1): allow programmatic overrides for env settings

Add functional options that let callers configure Prometheus and logging
settings without relying on environment variables. New options:

  WithPrometheusPushGateway, WithPrometheusNamespace, WithPrometheusLabelID
  WithLogFilePath, WithLogLevel, WithLogFormat
  WithoutEnvSettings

Precedence: programmatic options > env vars > defaults.
WithLogger takes precedence over log level/format options.

Construction order in New():
  1. Load settings from environment variables
  2. Apply options (overrides or WithoutEnvSettings)
  3. Build default output from final settings unless WithLogger was used

Default behavior (no new options) is unchanged.

Tests cover: env vars used by default, programmatic push gateway
override, log level/format application, WithLogger precedence over
log options, and WithoutEnvSettings ignoring env vars.

Author: nvloff-f3

.golangci.yml

@@ -82,6 +82,9 @@ linters:
       # Test files - relaxed rules for readability
       - linters: [dupword, lll, unparam, wrapcheck]
         path: _test\.go
+      # t.Setenv is incompatible with t.Parallel (Go constraint)
+      - linters: [paralleltest, tparallel]
+        path: options_settings_test\.go
       - linters: [staticcheck]
         path: _test\.go
         text: ST1003

pkg/f1/f1.go

@@ -34,18 +34,21 @@ type F1 struct {
 }
 
 type f1Options struct {
-	output        *ui.Output
-	staticMetrics map[string]string
+	output         *ui.Output
+	staticMetrics  map[string]string
+	loggerExplicit bool
 }
 
 // Option configures an F1 instance at construction.
 type Option func(*F1)
 
 // WithLogger specifies the logger for internal and scenario logs.
-// This disables F1_LOG_LEVEL and F1_LOG_FORMAT.
+// When used, WithLogLevel, WithLogFormat, F1_LOG_LEVEL and F1_LOG_FORMAT
+// have no effect because the caller controls the logger directly.
 func WithLogger(logger *slog.Logger) Option {
 	return func(f *F1) {
 		f.options.output = ui.NewDefaultOutputWithLogger(logger)
+		f.options.loggerExplicit = true
 	}
 }
 
@@ -57,21 +60,26 @@ func WithStaticMetrics(labels map[string]string) Option {
 }
 
 // New instantiates a new F1 CLI. Pass options to configure logger, metrics, etc.
+//
+// Construction order:
+//  1. Load settings from environment variables
+//  2. Apply options (may override individual settings or clear them via WithoutEnvSettings)
+//  3. Build default output from final settings unless WithLogger was used
 func New(opts ...Option) *F1 {
-	settings := envsettings.Get()
-
 	f := &F1{
 		scenarios: scenarios.New(),
 		profiling: &profiling{},
-		settings:  settings,
-		options: &f1Options{
-			output:        ui.NewDefaultOutput(settings.Log.SlogLevel(), settings.Log.IsFormatJSON()),
-			staticMetrics: nil,
-		},
+		settings:  envsettings.Get(),
+		options:   &f1Options{},
 	}
 	for _, opt := range opts {
 		opt(f)
 	}
+
+	if !f.options.loggerExplicit {
+		f.options.output = ui.NewDefaultOutput(f.settings.Log.SlogLevel(), f.settings.Log.IsFormatJSON())
+	}
+
 	return f
 }
 

pkg/f1/options_settings.go

@@ -0,0 +1,58 @@
+package f1
+
+import "github.com/form3tech-oss/f1/v3/internal/envsettings"
+
+// WithPrometheusPushGateway overrides the PROMETHEUS_PUSH_GATEWAY env var.
+func WithPrometheusPushGateway(url string) Option {
+	return func(f *F1) {
+		f.settings.Prometheus.PushGateway = url
+	}
+}
+
+// WithPrometheusNamespace overrides the PROMETHEUS_NAMESPACE env var.
+func WithPrometheusNamespace(ns string) Option {
+	return func(f *F1) {
+		f.settings.Prometheus.Namespace = ns
+	}
+}
+
+// WithPrometheusLabelID overrides the PROMETHEUS_LABEL_ID env var.
+func WithPrometheusLabelID(id string) Option {
+	return func(f *F1) {
+		f.settings.Prometheus.LabelID = id
+	}
+}
+
+// WithLogFilePath overrides the LOG_FILE_PATH env var.
+func WithLogFilePath(path string) Option {
+	return func(f *F1) {
+		f.settings.Log.FilePath = path
+	}
+}
+
+// WithLogLevel overrides the F1_LOG_LEVEL env var.
+// Accepts "debug", "info", "warn", "error" (case-insensitive).
+// Has no effect when WithLogger is also used.
+func WithLogLevel(level string) Option {
+	return func(f *F1) {
+		f.settings.Log.Level = level
+	}
+}
+
+// WithLogFormat overrides the F1_LOG_FORMAT env var.
+// Accepts "text" or "json" (case-insensitive).
+// Has no effect when WithLogger is also used.
+func WithLogFormat(format string) Option {
+	return func(f *F1) {
+		f.settings.Log.Format = format
+	}
+}
+
+// WithoutEnvSettings ignores all environment variables; settings start from
+// zero values (info level, text format, no prometheus). Must precede other
+// settings options in the option list so they are not overwritten.
+func WithoutEnvSettings() Option {
+	return func(f *F1) {
+		f.settings = envsettings.Settings{}
+	}
+}

pkg/f1/options_settings_test.go

@@ -0,0 +1,109 @@
+package f1_test
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/form3tech-oss/f1/v3/internal/log"
+	"github.com/form3tech-oss/f1/v3/pkg/f1"
+	"github.com/form3tech-oss/f1/v3/pkg/f1/f1testing"
+)
+
+func newPushGatewayServer(t *testing.T) (*httptest.Server, *atomic.Int32) {
+	t.Helper()
+
+	var count atomic.Int32
+	ts := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+		count.Add(1)
+	}))
+	t.Cleanup(ts.Close)
+
+	return ts, &count
+}
+
+func newF1WithScenario(name string, opts ...f1.Option) *f1.F1 {
+	inst := f1.New(opts...)
+	inst.AddScenario(name, func(_ context.Context, _ *f1testing.T) f1testing.RunFn {
+		return func(_ context.Context, _ *f1testing.T) {}
+	})
+
+	return inst
+}
+
+func runConstant(t *testing.T, inst *f1.F1, scenario string) {
+	t.Helper()
+
+	err := inst.Run(context.Background(), []string{
+		"run", "constant", scenario,
+		"--rate", "1/1s",
+		"--max-duration", "1s",
+		"--max-iterations", "1",
+	})
+	require.NoError(t, err)
+}
+
+func TestEnvVarsUsedByDefault(t *testing.T) {
+	ts, count := newPushGatewayServer(t)
+	t.Setenv("PROMETHEUS_PUSH_GATEWAY", ts.URL)
+
+	inst := newF1WithScenario("env_default")
+	runConstant(t, inst, "env_default")
+
+	require.Positive(t, count.Load(),
+		"PROMETHEUS_PUSH_GATEWAY env var should trigger metrics push")
+}
+
+func TestWithPrometheusPushGatewayOverridesEnv(t *testing.T) {
+	ts, count := newPushGatewayServer(t)
+	t.Setenv("PROMETHEUS_PUSH_GATEWAY", "http://env-should-not-be-used.invalid")
+
+	inst := newF1WithScenario("override", f1.WithPrometheusPushGateway(ts.URL))
+	runConstant(t, inst, "override")
+
+	require.Positive(t, count.Load(),
+		"programmatic WithPrometheusPushGateway should override env var")
+}
+
+func TestWithLogLevelAndFormat(t *testing.T) {
+	t.Setenv("PROMETHEUS_PUSH_GATEWAY", "")
+
+	inst := newF1WithScenario("log_opts",
+		f1.WithLogLevel("debug"),
+		f1.WithLogFormat("json"),
+	)
+	runConstant(t, inst, "log_opts")
+}
+
+func TestWithLoggerTakesPrecedenceOverLogOptions(t *testing.T) {
+	var buf bytes.Buffer
+	logger := log.NewTestLogger(&buf)
+
+	inst := newF1WithScenario("logger_precedence",
+		f1.WithLogger(logger),
+		f1.WithLogLevel("error"),
+		f1.WithLogFormat("json"),
+	)
+	runConstant(t, inst, "logger_precedence")
+
+	output := buf.String()
+	require.NotEmpty(t, output, "WithLogger's logger should capture output")
+	require.NotContains(t, output, `"level"`,
+		"explicit logger format (text) should be used, not JSON from WithLogFormat")
+}
+
+func TestWithoutEnvSettingsIgnoresEnvVars(t *testing.T) {
+	ts, count := newPushGatewayServer(t)
+	t.Setenv("PROMETHEUS_PUSH_GATEWAY", ts.URL)
+
+	inst := newF1WithScenario("no_env", f1.WithoutEnvSettings())
+	runConstant(t, inst, "no_env")
+
+	require.Equal(t, int32(0), count.Load(),
+		"WithoutEnvSettings should prevent env var PROMETHEUS_PUSH_GATEWAY from being used")
+}