Files
ExecuteR/tests/Backend.Tests/PowerShellParameterReaderTests.cs
Alphaeus Mote 1ef7d348d8 feat(scripts): read PowerShell param() blocks and check values on every start
The server reads a PowerShell script's param() block with PowerShell's own
parser (System.Management.Automation, parse only) through
POST /api/scripts/parameters/parse (scripts.view) and merges it into the
editor's parameters: the code owns name, type, required, default and
ValidateSet; Expansion and hand-written descriptions without help are kept;
parameters gone from the code are dropped. Only constant primitive defaults
and lists of them are imported; computed ones stay in the code. `using
assembly` is masked before parsing, since the parser would load it.

Manual runs, trigger saves and every firing share one check: a required
parameter needs a value or a default, and given values must fit. Schedules
store only the values set on them, so untouched ones follow the script's
defaults; a firing that no longer fits records why and does not run. Empty
values count as not given on the server and the agent alike.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 20:46:00 -05:00

339 lines
14 KiB
C#

using System.Management.Automation.Language;
using System.Text.Json;
using Backend.Scripts;
using Shared.Contracts.Models;
using Xunit;
namespace Backend.Tests;
public class PowerShellParameterReaderTests
{
private static ParameterReadResult Read(string script) => PowerShellParameterReader.Read(script);
private static ScriptParameter Param(string script, string name)
=> Read(script).Parameters.Single(p => p.Parameter.Name == name).Parameter;
private static string? Json(JsonElement? value) => value?.GetRawText();
[Fact]
public void TypesBecomeTextNumbersBooleansListsOrHashtables()
{
var result = Read("""
param(
[int]$Count,
[long]$Big,
[double]$Ratio,
[decimal]$Price,
[bool]$Enabled,
[switch]$Force,
[string]$Name,
[datetime]$When,
[guid]$Id,
[version]$Version,
[uri]$Endpoint,
[System.DayOfWeek]$Day,
[string[]]$Names,
[int[]]$Ports,
[System.Collections.Generic.List[double]]$Weights,
[hashtable]$Map,
[Nullable[int]]$Maybe,
$Untyped,
[Some.Unknown.Type]$Custom
)
""");
Assert.False(result.HasErrors);
Assert.True(result.HasParamBlock);
var byName = result.Parameters.ToDictionary(p => p.Parameter.Name, p => p.Parameter);
Assert.Equal(ScriptParameterType.Number, byName["Count"].Type);
Assert.Equal(ScriptParameterType.Number, byName["Big"].Type);
Assert.Equal(ScriptParameterType.Number, byName["Ratio"].Type);
Assert.Equal(ScriptParameterType.Number, byName["Price"].Type);
Assert.Equal(ScriptParameterType.Boolean, byName["Enabled"].Type);
Assert.Equal(ScriptParameterType.Boolean, byName["Force"].Type);
Assert.Equal("switch", byName["Force"].DeclaredType);
foreach (var text in new[] { "Name", "When", "Id", "Version", "Endpoint", "Day", "Untyped", "Custom" })
{
Assert.Equal(ScriptParameterType.String, byName[text].Type);
}
Assert.Equal("datetime", byName["When"].DeclaredType);
Assert.Null(byName["Untyped"].DeclaredType);
Assert.Equal((ScriptParameterType.Array, PrimitiveType.String), (byName["Names"].Type, byName["Names"].ElementType));
Assert.Equal((ScriptParameterType.Array, PrimitiveType.Number), (byName["Ports"].Type, byName["Ports"].ElementType));
Assert.Equal((ScriptParameterType.Array, PrimitiveType.Number), (byName["Weights"].Type, byName["Weights"].ElementType));
Assert.Equal(ScriptParameterType.Hashtable, byName["Map"].Type);
Assert.Equal(ScriptParameterType.Number, byName["Maybe"].Type);
Assert.Null(byName["Count"].ElementType);
// Declaration order is kept.
Assert.Equal("Count", result.Parameters[0].Parameter.Name);
Assert.Equal("Custom", result.Parameters[^1].Parameter.Name);
}
[Fact]
public void MandatoryMakesARequiredParameter()
{
var result = Read("""
[CmdletBinding()]
param(
[Parameter(Mandatory)][string]$Bare,
[Parameter(Mandatory = $true)][string]$Explicit,
[Parameter(Mandatory = 1)][string]$Numeric,
[Parameter(Mandatory = $false)][string]$Off,
[Parameter()][string]$Plain,
[System.Management.Automation.ParameterAttribute(Mandatory)][string]$FullName,
[Parameter(Mandatory, ParameterSetName = 'A')][Parameter(ParameterSetName = 'B')][string]$OneSetOnly,
[string]$NoAttribute
)
""");
var required = result.Parameters.Where(p => p.Parameter.Required).Select(p => p.Parameter.Name);
Assert.Equal(["Bare", "Explicit", "Numeric", "FullName"], required);
}
[Fact]
public void DescriptionsComeFromHelpMessageOrCommentBasedHelp()
{
var result = Read("""
<#
.SYNOPSIS
Does things.
.PARAMETER Path
Where the output
is written.
.PARAMETER Both
Comment help loses to HelpMessage.
#>
param(
[string]$Path,
[Parameter(HelpMessage = 'The message wins')][string]$Both,
[Parameter(HelpMessage = 'Asked when missing')][string]$Message,
[string]$Undocumented
)
""");
var byName = result.Parameters.ToDictionary(p => p.Parameter.Name);
Assert.Equal("Where the output is written.", byName["Path"].Parameter.Description);
Assert.True(byName["Path"].DescriptionFromCode);
Assert.Equal("The message wins", byName["Both"].Parameter.Description);
Assert.Equal("Asked when missing", byName["Message"].Parameter.Description);
Assert.Null(byName["Undocumented"].Parameter.Description);
Assert.False(byName["Undocumented"].DescriptionFromCode);
}
[Fact]
public void ConstantDefaultsAreImported()
{
const string script = """
param(
[string]$Text = 'a',
[string]$Quoted = "plain",
[int]$Count = 5,
[int]$Negative = -3,
[double]$Ratio = 1.5,
[int]$Kilo = 1kb,
[bool]$On = $true,
[switch]$Off = $false,
[string[]]$Names = @('a', 'b'),
[int[]]$Ports = @(80, 443),
[int[]]$Paren = (1, 2),
[string[]]$Empty = @(),
[string[]]$Single = 'only',
[string]$FromNumber = 42,
$UntypedNumber = 7,
$UntypedList = ('x', 'y'),
[string]$Nothing = $null
)
""";
Assert.False(Read(script).HasErrors);
Assert.Equal("\"a\"", Json(Param(script, "Text").DefaultValue));
Assert.Equal("\"plain\"", Json(Param(script, "Quoted").DefaultValue));
Assert.Equal("5", Json(Param(script, "Count").DefaultValue));
Assert.Equal("-3", Json(Param(script, "Negative").DefaultValue));
Assert.Equal("1.5", Json(Param(script, "Ratio").DefaultValue));
Assert.Equal("1024", Json(Param(script, "Kilo").DefaultValue));
Assert.Equal("true", Json(Param(script, "On").DefaultValue));
Assert.Equal("false", Json(Param(script, "Off").DefaultValue));
Assert.Equal("[\"a\",\"b\"]", Json(Param(script, "Names").DefaultValue));
Assert.Equal("[80,443]", Json(Param(script, "Ports").DefaultValue));
Assert.Equal("[1,2]", Json(Param(script, "Paren").DefaultValue));
Assert.Equal("[]", Json(Param(script, "Empty").DefaultValue));
Assert.Equal("[\"only\"]", Json(Param(script, "Single").DefaultValue));
Assert.Equal("\"42\"", Json(Param(script, "FromNumber").DefaultValue));
var untyped = Param(script, "UntypedNumber");
Assert.Equal((ScriptParameterType.Number, "7"), (untyped.Type, Json(untyped.DefaultValue)));
var list = Param(script, "UntypedList");
Assert.Equal((ScriptParameterType.Array, PrimitiveType.String), (list.Type, list.ElementType));
Assert.Equal("[\"x\",\"y\"]", Json(list.DefaultValue));
var nothing = Param(script, "Nothing");
Assert.Null(nothing.DefaultValue);
Assert.Null(nothing.DefaultExpression);
}
[Theory]
[InlineData("[string]$P = $env:TEMP", "$env:TEMP")]
[InlineData("[string]$P = \"$HOME\\out\"", "\"$HOME\\out\"")]
[InlineData("[string]$P = $(Get-Date)", "$(Get-Date)")]
[InlineData("[datetime]$P = (Get-Date)", "(Get-Date)")]
[InlineData("[int]$P = 1 + 2", "1 + 2")]
[InlineData("[int]$P = [int]5", "[int]5")]
[InlineData("[scriptblock]$P = { 'x' }", "{ 'x' }")]
[InlineData("[string[]]$P = @(Get-ChildItem)", "@(Get-ChildItem)")]
[InlineData("[string[]]$P = @('a', $x)", "@('a', $x)")]
[InlineData("[hashtable]$P = @{ a = 1 }", "@{ a = 1 }")]
[InlineData("[int]$P = 'not a number'", "'not a number'")]
public void NonConstantDefaultsAreLeftToPowerShell(string declaration, string expression)
{
Assert.False(Read($"param({declaration})").HasErrors);
var parameter = Param($"param({declaration})", "P");
Assert.Null(parameter.DefaultValue);
Assert.Equal(expression, parameter.DefaultExpression);
}
[Fact]
public void ValidateSetBecomesAllowedValues()
{
var script = """
param(
[ValidateSet('Debug', 'Release')][string]$Configuration = 'Release',
[ValidateSet('a', 'b', 'c')][string[]]$Letters,
[ValidateSet(1, 2)][int]$Level
)
""";
Assert.Equal(["Debug", "Release"], Param(script, "Configuration").AllowedValues);
Assert.Equal(["a", "b", "c"], Param(script, "Letters").AllowedValues);
Assert.Null(Param(script, "Level").AllowedValues); // a pick list is for text only
}
[Theory]
[InlineData("param([string]$Name")]
[InlineData("param([string]$Name = )")]
[InlineData("param([Parameter(Mandatory]$x)")]
[InlineData("function {")]
public void MalformedCodeReportsDiagnosticsWithoutThrowing(string script)
{
var result = Read(script);
Assert.True(result.HasErrors);
var error = result.Diagnostics.First(d => d.Severity == "error");
Assert.False(string.IsNullOrWhiteSpace(error.Message));
Assert.True(error.Line >= 1 && error.Column >= 1);
}
[Fact]
public void PathologicalNestingDoesNotThrow()
{
var result = Read(new string('(', 20_000) + "1" + new string(')', 20_000));
Assert.False(result.HasParamBlock);
}
[Fact]
public void AScriptWithoutParamBlockDeclaresNothing()
{
var result = Read("Write-Output 'hello'\nfunction Inner { param($x) }");
Assert.False(result.HasErrors);
Assert.False(result.HasParamBlock);
Assert.Empty(result.Parameters);
}
[Fact]
public void TypesThatCannotComeFromTextAreFlagged()
{
var result = Read("param([pscredential]$Credential, [string]$Name)");
var warning = Assert.Single(result.Diagnostics);
Assert.Equal("warning", warning.Severity);
Assert.Contains("$Credential", warning.Message);
Assert.False(result.HasErrors);
}
[Fact]
public void UsingAssemblyIsNeverLoaded()
{
var dir = Directory.CreateTempSubdirectory("executer-parse-");
try
{
// Not an assembly: an attempt to load it would be reported.
var dll = Path.Combine(dir.FullName, "Probe.dll");
File.WriteAllText(dll, "not an assembly");
var script = $"using assembly '{dll}'\nUsing <# c #> Assembly System.Xml\nparam([string]$Name = 'using assembly kept')";
// Unguarded, PowerShell's parser does try to load it.
Parser.ParseInput(script, out _, out var unguarded);
Assert.Contains(unguarded, e => e.Message.Contains("assembly", StringComparison.OrdinalIgnoreCase));
var result = Read(script);
Assert.False(result.HasErrors, string.Join("; ", result.Diagnostics.Select(d => d.Message)));
Assert.Equal("\"using assembly kept\"", Json(Param(script, "Name").DefaultValue));
Assert.DoesNotContain(AppDomain.CurrentDomain.GetAssemblies(), a => !a.IsDynamic && a.Location == dll);
}
finally
{
dir.Delete(recursive: true);
}
}
[Fact]
public void UsingModuleIsNeverImported()
{
var dir = Directory.CreateTempSubdirectory("executer-parse-");
try
{
var marker = Path.Combine(dir.FullName, "ran.txt");
var module = Path.Combine(dir.FullName, "Probe.psm1");
File.WriteAllText(module, $"Set-Content -Path '{marker}' -Value ran\nclass Probe {{ }}");
var result = Read($"using module '{module}'\nparam([Probe]$Thing, [string]$Name)");
Assert.Equal(["Thing", "Name"], result.Parameters.Select(p => p.Parameter.Name));
Assert.False(File.Exists(marker));
}
finally
{
dir.Delete(recursive: true);
}
}
[Fact]
public void MergeTakesTheCodesShapeAndKeepsWhatTheCodeDoesNotSay()
{
var declared = Read("""
<#
.PARAMETER Documented
From help.
#>
param(
[Parameter(Mandatory)][int]$Count = 3,
[string]$Path,
[string]$Documented
)
""").Parameters;
var current = new List<ScriptParameter>
{
new("path", ScriptParameterType.Number, Description: "Hand-written", Expansion: ValueExpansion.Literal),
new("Documented", ScriptParameterType.String, Description: "Replaced by help"),
new("Gone", ScriptParameterType.String),
new("Count", ScriptParameterType.String, Required: false, Expansion: ValueExpansion.Literal),
};
var merged = ScriptParameterSync.Merge(current, declared);
Assert.Equal(["Count", "Path", "Documented"], merged.Select(p => p.Name));
var count = merged[0];
Assert.Equal((ScriptParameterType.Number, true, "3"), (count.Type, count.Required, Json(count.DefaultValue)));
Assert.Equal(ValueExpansion.Literal, count.Expansion);
var path = merged[1];
Assert.Equal((ScriptParameterType.String, "Hand-written", ValueExpansion.Literal), (path.Type, path.Description, path.Expansion));
Assert.Equal("From help.", merged[2].Description);
}
}