feat: add --dry-run flag for listing tests by tier

Makefile

@@ -95,6 +95,17 @@ e2e-ci: build ## Run E2E tests with CI configuration
 	mkdir -p $(OUTPUT_DIR)
 	TESTDATA_DIR=$(PWD)/testdata ./$(BINARY_NAME) test --configs ci --junit-report $(OUTPUT_DIR)/junit.xml
 
+.PHONY: list-tests
+list-tests: build ## List E2E tests by tier without executing (dry-run)
+	@echo "=== tier0 ==="
+	TESTDATA_DIR=$(PWD)/testdata ./$(BINARY_NAME) test --dry-run --label-filter=tier0
+	@echo ""
+	@echo "=== tier1 ==="
+	TESTDATA_DIR=$(PWD)/testdata ./$(BINARY_NAME) test --dry-run --label-filter=tier1
+	@echo ""
+	@echo "=== tier2 ==="
+	TESTDATA_DIR=$(PWD)/testdata ./$(BINARY_NAME) test --dry-run --label-filter=tier2
+
 ##@ Code Quality
 
 .PHONY: fmt

cmd/hyperfleet-e2e/test/cmd.go

@@ -28,6 +28,7 @@ var args struct {
 	focusTests  string
 	skipTests   string
 	junitReport string
+	dryRun      bool
 }
 
 func init() {
@@ -42,6 +43,8 @@ func init() {
 		"Skip tests matching this regex")
 	pfs.StringVar(&args.junitReport, "junit-report", "",
 		"Path to write JUnit XML report")
+	pfs.BoolVar(&args.dryRun, "dry-run", false,
+		"List matching specs without executing them")
 }
 
 func run(cmd *cobra.Command, argv []string) {
@@ -56,6 +59,7 @@ func run(cmd *cobra.Command, argv []string) {
 	_ = viper.BindPFlag(config.Tests.GinkgoFocus, pfs.Lookup("focus"))
 	_ = viper.BindPFlag(config.Tests.GinkgoSkip, pfs.Lookup("skip"))
 	_ = viper.BindPFlag(config.Tests.JUnitReportPath, pfs.Lookup("junit-report"))
+	_ = viper.BindPFlag(config.Tests.GinkgoDryRun, pfs.Lookup("dry-run"))
 
 	// Bind parent command flags (api-url, logging flags)
 	parentFlags := cmd.Parent().PersistentFlags()
@@ -70,6 +74,7 @@ func run(cmd *cobra.Command, argv []string) {
 	_ = viper.BindEnv(config.Tests.GinkgoSkip, "GINKGO_SKIP")
 	_ = viper.BindEnv(config.Tests.JUnitReportPath, "JUNIT_REPORT_PATH")
 	_ = viper.BindEnv(config.Tests.SuiteTimeout, "SUITE_TIMEOUT")
+	_ = viper.BindEnv(config.Tests.GinkgoDryRun, "GINKGO_DRY_RUN")
 
 	// Load and validate config (fast failure before entering Ginkgo)
 	cfg, err := config.Load()

docs/getting-started.md

@@ -67,21 +67,36 @@ The framework:
 # Run cluster tier0 tests only
 ./bin/hyperfleet-e2e test --label-filter="tier0" --focus "\[Suite: cluster\]"
 
-
 # Deep debug mode (add API calls and framework internals)
 ./bin/hyperfleet-e2e test --log-level=debug
 ```
 
+## Listing Tests Without Execution
+
+Use `--dry-run` to discover which specs match your filters without connecting to the API or creating resources. No `--api-url` is required in dry-run mode.
+
+```bash
+# List all tier0 tests
+./bin/hyperfleet-e2e test --dry-run --label-filter=tier0
+
+# List tier1 cluster tests
+./bin/hyperfleet-e2e test --dry-run --label-filter=tier1 --focus "\[Suite: cluster\]"
+
+# List tests for each tier via Makefile
+make list-tests
+```
+
 **Note**: The default output already shows detailed test execution steps. If a test fails, you can usually diagnose the issue from the logs without re-running in debug mode. Use `--log-level=debug` when you need to see API calls and framework internals. See [Debugging Guide](debugging.md) for more debugging techniques.
 
 ## Common Commands
 
 ```bash
-make build      # Build binary
-make test       # Run unit tests
-make e2e        # Run E2E tests
-make lint       # Run linter
-make generate   # Regenerate OpenAPI client
+make build       # Build binary
+make test        # Run unit tests
+make e2e         # Run E2E tests
+make list-tests  # List tests by tier (dry-run, no API required)
+make lint        # Run linter
+make generate    # Regenerate OpenAPI client
 ```
 
 ## Troubleshooting

pkg/config/config.go

@@ -63,12 +63,17 @@ var Tests = struct {
 	// JUnitReportPath is the path to write JUnit XML report
 	// Env: JUNIT_REPORT_PATH
 	JUnitReportPath string
+
+	// GinkgoDryRun lists matching specs without executing them
+	// Env: GINKGO_DRY_RUN
+	GinkgoDryRun string
 }{
 	GinkgoLabelFilter: "tests.ginkgoLabelFilter",
 	GinkgoFocus:       "tests.focus",
 	GinkgoSkip:        "tests.ginkgoSkip",
 	SuiteTimeout:      "tests.suiteTimeout",
 	JUnitReportPath:   "tests.junitReportPath",
+	GinkgoDryRun:      "tests.dryRun",
 }
 
 // Log config keys
@@ -404,8 +409,10 @@ func (c *Config) applyDefaults() {
 
 // Validate validates configuration with detailed error messages
 func (c *Config) Validate() error {
-	// Validate API URL requirement
-	if c.API.URL == "" {
+	dryRun := viper.GetBool(Tests.GinkgoDryRun)
+
+	// Validate API URL requirement (not needed for dry-run listing)
+	if !dryRun && c.API.URL == "" {
 		return fmt.Errorf(`configuration validation failed:
   - Field 'Config.API.URL' is required
     Please provide API URL (in order of priority):

pkg/e2e/e2e.go

@@ -74,6 +74,10 @@ func configureGinkgoFromViper(suiteConfig *types.SuiteConfig, reporterConfig *ty
 		reporterConfig.JUnitReport = junitReport
 	}
 
+	if viper.GetBool(config.Tests.GinkgoDryRun) {
+		suiteConfig.DryRun = true
+	}
+
 	reporterConfig.NoColor = true
 	// Enable verbose test output for info and debug levels
 	logLevel := viper.GetString(config.Log.Level)