Azure
diff --git a/‎cli/azd/AGENTS.md‎
Lines changed: 4 additions & 0 deletions b/‎cli/azd/AGENTS.md‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎cli/azd/CONTRIBUTING.md‎
Lines changed: 21 additions & 0 deletions b/‎cli/azd/CONTRIBUTING.md‎
Lines changed: 21 additions & 0 deletions
diff --git a/‎cli/azd/docs/environment-variables.md‎
Lines changed: 22 additions & 7 deletions b/‎cli/azd/docs/environment-variables.md‎
Lines changed: 22 additions & 7 deletions
diff --git a/‎cli/azd/docs/recording-functional-tests-guide.md‎
Lines changed: 36 additions & 1 deletion b/‎cli/azd/docs/recording-functional-tests-guide.md‎
Lines changed: 36 additions & 1 deletion
diff --git a/‎cli/azd/magefile.go‎
Lines changed: 140 additions & 51 deletions b/‎cli/azd/magefile.go‎
Lines changed: 140 additions & 51 deletions
@@ -75,6 +75,10 @@ When writing tests, prefer table-driven tests. Use testify/mock for mocking.
 
 > **Tip**: The `/azd-preflight` Copilot skill runs all these checks and auto-fixes issues. See `.github/skills/azd-preflight/`.
 
+Additional mage targets:
+
+- `mage record` — re-record functional test cassettes against a live Azure subscription. Accepts an optional `-filter=TestName` flag to re-record specific tests. Typically only core maintainers need to run this; external contributors can rely on playback mode (the default) which requires no Azure access. Requires `azd auth login` and a configured test subscription (see `docs/recording-functional-tests-guide.md`).
+
 ```bash
 gofmt -s -w .
 go fix ./...
 
@@ -59,6 +59,27 @@ mage preflight
 
 > **Tip**: If you're using GitHub Copilot, the `/azd-preflight` skill runs `mage preflight` and auto-fixes any issues it discovers.
 
+### Re-recording functional test cassettes
+
+> **Note**: Re-recording is typically a core-maintainer workflow and requires an Azure subscription. External contributors can run the tests in the default playback mode, which replays stored cassettes and needs no Azure access.
+
+Re-record stale functional test recordings against a live Azure subscription:
+
+```bash
+cd cli/azd
+mage record                          # re-record all playback tests
+mage record -filter=Test_CLI_Quota   # re-record only matching tests
+```
+
+Core maintainers configure the test subscription and tenant once via `azd config`:
+
+```bash
+azd config set defaults.test.subscription <SUBSCRIPTION_ID>
+azd config set defaults.test.tenant <TENANT_ID>
+```
+
+These values are stored in your user-level azd config and persist across sessions. You can also set them via environment variables (`AZD_TEST_AZURE_SUBSCRIPTION_ID`, `AZD_TEST_TENANT_ID`), which take precedence. Any Azure subscription you have access to works; the `defaults.test.*` namespace is kept separate from the top-level `defaults.*` so test config does not affect regular `azd` usage. See the [recording guide](./docs/recording-functional-tests-guide.md) for details.
+
 Run tests:
 
 ```bash
 
@@ -230,13 +230,28 @@ These variables are used by the Terraform provider integration to authenticate w
 ## Test Variables
 
 > **Warning**: Test variables are used by the `azd` test suite only and are not intended for end users.
-
-| Variable | Description |
-| --- | --- |
-| `AZD_TEST_CLIENT_ID` | The client ID for test authentication. |
-| `AZD_TEST_TENANT_ID` | The tenant ID for test authentication. |
-| `AZD_TEST_AZURE_SUBSCRIPTION_ID` | The Azure subscription ID for tests. |
-| `AZD_TEST_AZURE_LOCATION` | The Azure location for tests. |
+>
+> **Tip**: Instead of setting environment variables for every session, you can persist test defaults
+> in your user-level `azd` config. These config keys act as fallbacks when the corresponding
+> environment variable is not set:
+>
+> ```bash
+> azd config set defaults.test.subscription <SUBSCRIPTION_ID>
+> azd config set defaults.test.tenant <TENANT_ID>
+> azd config set defaults.test.location <LOCATION>
+> ```
+>
+> Resolution order: environment variable → `defaults.test.*` → `defaults.*` (global default).
+> Note: `AZD_TEST_TENANT_ID` only falls back to `defaults.test.tenant` (no
+> `defaults.tenant` global fallback). Config fallbacks are only consulted when
+> the `CI` environment variable is unset.
+
+| Variable | Description | Config Fallback |
+| --- | --- | --- |
+| `AZD_TEST_CLIENT_ID` | The client ID for test authentication. | — |
+| `AZD_TEST_TENANT_ID` | The tenant ID for test authentication. | `defaults.test.tenant` |
+| `AZD_TEST_AZURE_SUBSCRIPTION_ID` | The Azure subscription ID for tests. | `defaults.test.subscription` |
+| `AZD_TEST_AZURE_LOCATION` | The Azure location for tests. | `defaults.test.location` |
 | `AZD_TEST_CLI_VERSION` | Overrides the CLI version reported during tests. |
 | `AZD_TEST_FIXED_CLOCK_UNIX_TIME` | Sets a fixed clock time (Unix epoch) for deterministic tests. |
 | `AZD_TEST_HTTPS_PROXY` | The HTTPS proxy URL for tests. |
 
@@ -262,7 +262,42 @@ This helper (from `test/functional/aspire_test.go`) deletes subscription deploym
 
 ## Re-recording an Existing Test
 
-### Local Development
+> **Note**: Re-recording is typically a core-maintainer workflow. External contributors generally do not need to re-record cassettes; the default playback mode replays stored interactions and requires no Azure access. Open an issue if a cassette appears stale.
+
+### Using `mage record` (Recommended)
+
+The easiest way to re-record tests is the `mage record` target:
+
+```bash
+cd cli/azd
+mage record -filter=Test_CLI_MyNewFeature   # re-record a specific test
+mage record                                  # re-record all playback tests
+```
+
+`mage record` handles building the `azd-record` binary, setting `AZURE_RECORD_MODE=record`, and running the test with a 30-minute timeout.
+
+#### Configuring the Test Subscription
+
+Tests need an Azure subscription and tenant. Any subscription you have access to works — the `defaults.test.*` keys are a separate namespace so test configuration does not affect regular `azd` defaults. Configure them once with `azd config` (persists across sessions):
+
+```bash
+azd config set defaults.test.subscription <SUBSCRIPTION_ID>
+azd config set defaults.test.tenant <TENANT_ID>
+```
+
+The resolution order is: environment variable → `defaults.test.*` config → `defaults.*` config.
+Note: tenant only falls back to `defaults.test.tenant` (no `defaults.tenant` global fallback).
+Config fallbacks are only consulted when the `CI` environment variable is unset.
+
+| Setting | Environment Variable | Config Key |
+|---------|---------------------|------------|
+| Subscription | `AZD_TEST_AZURE_SUBSCRIPTION_ID` | `defaults.test.subscription` |
+| Tenant | `AZD_TEST_TENANT_ID` | `defaults.test.tenant` |
+| Location | `AZD_TEST_AZURE_LOCATION` | `defaults.test.location` |
+
+### Manual Re-recording
+
+If you prefer manual control:
 
 1. **Delete existing recording**:
    ```bash
 
@@ -123,28 +123,13 @@ func (Dev) Uninstall() error {
 //
 // Usage: mage preflight
 func Preflight() error {
-	// Disable Go workspace mode so preflight mirrors CI, which has no go.work file.
-	// Without this, a local go.work can silently resolve different module versions
-	// than go.mod alone, masking build failures that only appear in CI.
-	defer setEnvScoped("GOWORK", "off")()
-
-	repoRoot, err := findRepoRoot()
+	azdDir, cleanup, err := mageInit()
 	if err != nil {
 		return err
 	}
-	azdDir := filepath.Join(repoRoot, "cli", "azd")
+	defer cleanup()
 
-	// Pin GOTOOLCHAIN to the version declared in go.mod when it isn't already
-	// set. When the system Go is older (e.g. 1.25) and go.mod says 1.26,
-	// parallel compilations can race the auto-download, producing "compile:
-	// version X does not match go tool version Y" errors. Pinning upfront
-	// avoids this. We skip the override when GOTOOLCHAIN is already set so
-	// that a user's explicit choice (or a newer Go) is respected.
-	if _, hasToolchain := os.LookupEnv("GOTOOLCHAIN"); !hasToolchain {
-		if ver, err := goModVersion(azdDir); err == nil && ver != "" {
-			defer setEnvScoped("GOTOOLCHAIN", "go"+ver)()
-		}
-	}
+	repoRoot := filepath.Dir(filepath.Dir(azdDir))
 
 	// Check required tools are installed before running anything.
 	if err := requireTool("golangci-lint",
@@ -381,8 +366,10 @@ func Preflight() error {
 
 		// 8. Playback tests
 		wg2.Go(func() {
-			playbackEnv := append(skipBuildEnv, "AZURE_RECORD_MODE=playback")
-			if err := runPlaybackTestsWithEnv(azdDir, playbackEnv); err != nil {
+			if err := runFunctionalTests(azdDir, testRunOpts{
+				mode: "playback",
+				env:  skipBuildEnv,
+			}); err != nil {
 				results[checkPlayback] = checkResult{"fail", err.Error(), ""}
 			} else {
 				results[checkPlayback] = checkResult{"pass", "", ""}
@@ -424,69 +411,167 @@ func Preflight() error {
 //
 // Usage: mage playbackTests
 func PlaybackTests() error {
-	defer setEnvScoped("GOWORK", "off")()
+	azdDir, cleanup, err := mageInit()
+	if err != nil {
+		return err
+	}
+	defer cleanup()
 
-	repoRoot, err := findRepoRoot()
+	return runFunctionalTests(azdDir, testRunOpts{mode: "playback"})
+}
+
+// Record re-records functional test playback cassettes against live Azure.
+// Usage:
+//
+//	mage record                              # re-record ALL playback tests
+//	mage record -filter=TestName             # re-record tests matching filter
+//
+// Requires:
+//   - Azure authentication (azd auth login)
+//   - Test subscription config (azd config set defaults.test.subscription/tenant/location)
+//     OR equivalent AZD_TEST_* environment variables
+//
+// The azd-record binary (built with -tags=record) is built on demand by
+// azdcli.NewCLI via buildRecordOnce when tests run in record mode. To use a
+// custom pre-built binary, set CLI_TEST_AZD_PATH before invoking mage record.
+func Record(filter *string) error {
+	azdDir, cleanup, err := mageInit()
 	if err != nil {
 		return err
 	}
-	azdDir := filepath.Join(repoRoot, "cli", "azd")
+	defer cleanup()
+
+	return runFunctionalTests(azdDir, testRunOpts{
+		mode:    "record",
+		filter:  filter,
+		verbose: true,
+	})
+}
+
+// mageInit sets up the standard mage environment (GOWORK=off, GOTOOLCHAIN pin)
+// and returns the cli/azd directory path. Callers must defer the returned
+// cleanup function to restore environment variables.
+func mageInit() (azdDir string, cleanup func(), err error) {
+	restoreGowork := setEnvScoped("GOWORK", "off")
 
-	// Pin GOTOOLCHAIN (see Preflight for rationale).
+	repoRoot, err := findRepoRoot()
+	if err != nil {
+		restoreGowork()
+		return "", nil, err
+	}
+	azdDir = filepath.Join(repoRoot, "cli", "azd")
+
+	// Pin GOTOOLCHAIN to the version declared in go.mod when it isn't already
+	// set. Prevents parallel compilation races when the system Go version
+	// differs from go.mod (see Preflight for full rationale).
+	var restoreToolchain func()
 	if _, hasToolchain := os.LookupEnv("GOTOOLCHAIN"); !hasToolchain {
 		if ver, err := goModVersion(azdDir); err == nil && ver != "" {
-			defer setEnvScoped("GOTOOLCHAIN", "go"+ver)()
+			restoreToolchain = setEnvScoped("GOTOOLCHAIN", "go"+ver)
 		}
 	}
 
-	return runPlaybackTests(azdDir)
+	cleanup = func() {
+		if restoreToolchain != nil {
+			restoreToolchain()
+		}
+		restoreGowork()
+	}
+	return azdDir, cleanup, nil
 }
 
-// runPlaybackTests discovers test recordings and runs matching functional
-// tests in playback mode (AZURE_RECORD_MODE=playback).
-func runPlaybackTests(azdDir string) error {
-	return runPlaybackTestsWithEnv(azdDir, nil)
+// testRunOpts configures how runFunctionalTests discovers and executes
+// functional tests with recorded HTTP interactions.
+type testRunOpts struct {
+	mode    string   // "record" or "playback"
+	filter  *string  // optional test name filter (substring match)
+	verbose bool     // add -v flag
+	env     []string // additional env vars beyond AZURE_RECORD_MODE
 }
 
-// runPlaybackTestsWithEnv is like runPlaybackTests but accepts additional
-// environment variables (e.g. CLI_TEST_SKIP_BUILD=true for parallel runs).
-func runPlaybackTestsWithEnv(azdDir string, extraEnv []string) error {
+// runFunctionalTests discovers playback tests from recordings, applies an
+// optional name filter, and runs them via "go test" with the given mode
+// and environment variables.
+func runFunctionalTests(azdDir string, opts testRunOpts) error {
+	if opts.mode != "record" && opts.mode != "playback" {
+		return fmt.Errorf("invalid test mode %q: must be %q or %q", opts.mode, "record", "playback")
+	}
+
 	recordingsDir := filepath.Join(
 		azdDir, "test", "functional", "testdata", "recordings",
 	)
-	names, err := discoverPlaybackTests(recordingsDir)
+	// In record mode, ignore the stale-recording exclusion list so users can
+	// re-record those tests via `mage record -filter=<name>`. In playback
+	// mode, skip them so they don't block preflight.
+	names, err := discoverPlaybackTests(recordingsDir, opts.mode == "playback")
 	if err != nil {
 		return err
 	}
 	if len(names) == 0 {
-		fmt.Println("No recording files found — skipping playback tests.")
+		fmt.Printf("No recording files found — skipping %s tests.\n", opts.mode)
 		return nil
 	}
 
+	// Apply optional test filter.
+	if opts.filter != nil {
+		var filtered []string
+		for _, name := range names {
+			if strings.Contains(name, *opts.filter) || name == *opts.filter {
+				filtered = append(filtered, name)
+			}
+		}
+		if len(filtered) == 0 {
+			fmt.Printf("No tests match filter %q in %s mode. Available tests:\n", *opts.filter, opts.mode)
+			for _, name := range names {
+				fmt.Printf("  • %s\n", name)
+			}
+			return fmt.Errorf("no tests match filter %q", *opts.filter)
+		}
+		names = filtered
+	}
+
+	// Build test -run pattern from discovered names.
 	escaped := make([]string, len(names))
 	for i, name := range names {
 		escaped[i] = regexp.QuoteMeta(name)
 	}
 	pattern := "^(" + strings.Join(escaped, "|") + ")(/|$)"
-	fmt.Printf("Running %d tests in playback mode...\n", len(names))
-
-	env := append(extraEnv, "AZURE_RECORD_MODE=playback")
-	return runStreamingWithEnv(
-		azdDir,
-		env,
-		"go", "test", "-run", pattern,
-		"./test/functional", "-timeout", "30m", "-count=1",
-	)
+
+	fmt.Printf("Running %d test(s) in %s mode...\n", len(names), opts.mode)
+	if opts.verbose {
+		for _, name := range names {
+			fmt.Printf("  • %s\n", name)
+		}
+	}
+
+	env := []string{"AZURE_RECORD_MODE=" + opts.mode}
+	env = append(env, opts.env...)
+
+	args := []string{"test", "-run", pattern, "./test/functional", "-timeout", "30m", "-count=1"}
+	if opts.verbose {
+		args = append(args, "-v")
+	}
+
+	return runStreamingWithEnv(azdDir, env, "go", args...)
 }
 
 // excludedPlaybackTests lists tests whose recordings are known to be stale.
 // These are excluded from automatic playback so they don't block preflight.
-// Re-record the test to remove it from this list.
-var excludedPlaybackTests = map[string]string{}
+// Re-record the test (mage record -filter=<name>) to remove it from this list.
+// Re-recording requires access to the TME subscription — see CONTRIBUTING.md.
+var excludedPlaybackTests = map[string]string{
+	"Test_CLI_VsServer":                "stale recording; re-record requires TME access (#7780)",
+	"Test_CLI_Deploy_SlotDeployment":   "stale recording; re-record requires TME access (#7780)",
+	"Test_CLI_Up_Down_ContainerAppJob": "stale recording; re-record requires TME access (#7014)",
+}
 
 // discoverPlaybackTests scans the recordings directory for .yaml files and
-// subdirectories, returning unique top-level Go test function names.
-func discoverPlaybackTests(recordingsDir string) ([]string, error) {
+// subdirectories, returning unique top-level Go test function names. When
+// applyExclusions is true, tests in excludedPlaybackTests are filtered out
+// (used in playback mode to avoid blocking preflight on known-stale
+// recordings). In record mode, callers pass false so excluded tests can
+// be re-recorded via `mage record -filter=<name>`.
+func discoverPlaybackTests(recordingsDir string, applyExclusions bool) ([]string, error) {
 	entries, err := os.ReadDir(recordingsDir)
 	if err != nil {
 		if errors.Is(err, fs.ErrNotExist) {
@@ -519,9 +604,13 @@ func discoverPlaybackTests(recordingsDir string) ([]string, error) {
 		seen[cassette] = true
 	}
 
-	// Remove tests with known stale recordings.
-	for name := range excludedPlaybackTests {
-		delete(seen, name)
+	// Remove tests with known stale recordings, but only when requested
+	// (i.e. in playback mode). Record mode needs to see all tests so users
+	// can re-record the excluded ones via `mage record -filter=<name>`.
+	if applyExclusions {
+		for name := range excludedPlaybackTests {
+			delete(seen, name)
+		}
 	}
 
 	if len(seen) == 0 {