Test: EnvironmentVariableMutatorOptions API proposal

[Tyriar]

Refs: #179476

• macOS @meganrogge (zsh, fish)
• linux @rzhao271 (bash)
• windows: @karrtikr (pwsh)

Complexity: 4

Create Issue

---

The EnvironmentVariableCollection allows extensions to change the terminal's process environment which enables features like the js-debug auto attach and git's authentication being handled VS Code. It's getting a new API proposal that allows specifying exactly when the variable "mutators" are applied.

Previously they would always be applied as the process is being created but now they can optionally be applied in the shell integration script as well which is done after shell initialization scripts are run. The specific problem this helps us solve is when setting the environment is critically important, such as environment activation in the Python extension, we can ensure that environment variables being touched in shell init scripts doesn't negatively impact the feature (when shell integration is enabled).

Current proposal:

declare module 'vscode' {

	// https://github.com/microsoft/vscode/issues/179476

	/**
	 * Options applied to the mutator.
	 */
	export interface EnvironmentVariableMutatorOptions {
		/**
		 * Apply to the environment just before the process is created.
		 *
		 * Defaults to true.
		 */
		applyAtProcessCreation?: boolean;

		/**
		 * Apply to the environment in the shell integration script. Note that this _will not_ apply
		 * the mutator if shell integration is disabled or not working for some reason.
		 *
		 * Defaults to false.
		 */
		applyAtShellIntegration?: boolean;
	}

	/**
	 * A type of mutation and its value to be applied to an environment variable.
	 */
	export interface EnvironmentVariableMutator {
		/**
		 * Options applied to the mutator.
		 */
		readonly options: EnvironmentVariableMutatorOptions;
	}

	export interface EnvironmentVariableCollection extends Iterable<[variable: string, mutator: EnvironmentVariableMutator]> {
		/**
		 * @param options Options applied to the mutator.
		 */
		replace(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void;

		/**
		 * @param options Options applied to the mutator.
		 */
		append(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void;

		/**
		 * @param options Options applied to the mutator.
		 */
		prepend(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void;
	}
}

Test the following:

• The API docs make sense
• replace, append and prepend all apply the variable as expected
• Test with and without options - to tell the difference between applyAtShellIntegration, try changing variables in your shell startup script, that should happen after applyAtProcessCreation and before applyAtShellIntegration
• Test all combinations of applyAtProcessCreation and applyAtShellIntegration.
• When applyAtProcessCreation is false and applyAtShellIntegration is false or undefined it should throw.
• applyAtShellIntegration should not apply when shell integration is disabled (terminal.integrated.shellIntegration.enabled)