Test-Expression

2.4.0

en-us/Test-Expression-help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns="http://msh" schema="maml">
 
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
<command:details><command:name>Test-Expression</command:name>
<command:verb>Test</command:verb>
<command:noun>Expression</command:noun>
<maml:description><maml:para>Test a PowerShell expression.
</maml:para>
</maml:description>
</command:details>
<maml:description><maml:para>This command will test a PowerShell expression or scriptblock for a specified number of times and calculate the average runtime, in milliseconds, over all the tests. The output will also show the median and trimmed values.
</maml:para>
<maml:para>The median is calculated by sorting the values in ascending order and selecting the value in the center of the array. If the array has an even number of elements then the median is the average of the two values in the center. The trimmed value will toss out the lowest and highest values and average the remaining values. This may be the most accurate indication as it will eliminate any small values which might come from caching and any large values which may come a temporary shortage of resources. You will only get a value if you run more than 1 test.
</maml:para>
</maml:description>
<command:syntax><command:syntaxItem><maml:name>Test-Expression</maml:name>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="sb"><maml:name>Expression</maml:name>
<maml:Description><maml:para>The scriptblock you want to test.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue>
<dev:type><maml:name>ScriptBlock</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>None</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>ArgumentList</maml:name>
<maml:Description><maml:para>An array of parameters to pass to the test scriptblock. Arguments are positional. If passing an array for a value enter with @().
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Object[]</command:parameterValue>
<dev:type><maml:name>Object[]</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>None</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"><maml:name>Count</maml:name>
<maml:Description><maml:para>The number of times to test the scriptblock.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Int32</command:parameterValue>
<dev:type><maml:name>Int32</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>1</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="sleep"><maml:name>Interval</maml:name>
<maml:Description><maml:para>How much time to sleep in seconds between each test. Maximum is 60. You may want to use a sleep interval to mitigate possible caching effects.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Double</command:parameterValue>
<dev:type><maml:name>Double</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>0.5</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="ie"><maml:name>IncludeExpression</maml:name>
<maml:Description><maml:para>Include the test scriptblock in the output.
</maml:para>
</maml:Description>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>AsJob</maml:name>
<maml:Description><maml:para>Run the tests as a background job.
</maml:para>
</maml:Description>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
</command:syntaxItem>
<command:syntaxItem><maml:name>Test-Expression</maml:name>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="sb"><maml:name>Expression</maml:name>
<maml:Description><maml:para>The scriptblock you want to test.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue>
<dev:type><maml:name>ScriptBlock</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>None</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>ArgumentList</maml:name>
<maml:Description><maml:para>An array of parameters to pass to the test scriptblock. Arguments are positional. If passing an array for a value enter with @().
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Object[]</command:parameterValue>
<dev:type><maml:name>Object[]</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>None</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"><maml:name>Count</maml:name>
<maml:Description><maml:para>The number of times to test the scriptblock.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Int32</command:parameterValue>
<dev:type><maml:name>Int32</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>1</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="ie"><maml:name>IncludeExpression</maml:name>
<maml:Description><maml:para>Include the test scriptblock in the output.
</maml:para>
</maml:Description>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>AsJob</maml:name>
<maml:Description><maml:para>Run the tests as a background job.
</maml:para>
</maml:Description>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="min"><maml:name>RandomMinimum</maml:name>
<maml:Description><maml:para>You can also specify a random interval by providing a random minimum and maximum values in seconds.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Double</command:parameterValue>
<dev:type><maml:name>Double</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>0</dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="max"><maml:name>RandomMaximum</maml:name>
<maml:Description><maml:para>You can also specify a random interval by providing a random minimum and maximum values in seconds.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Double</command:parameterValue>
<dev:type><maml:name>Double</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>0</dev:defaultValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters><command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="sb"><maml:name>Expression</maml:name>
<maml:Description><maml:para>The scriptblock you want to test.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue>
<dev:type><maml:name>ScriptBlock</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>None</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>ArgumentList</maml:name>
<maml:Description><maml:para>An array of parameters to pass to the test scriptblock. Arguments are positional. If passing an array for a value enter with @().
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Object[]</command:parameterValue>
<dev:type><maml:name>Object[]</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>None</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"><maml:name>Count</maml:name>
<maml:Description><maml:para>The number of times to test the scriptblock.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Int32</command:parameterValue>
<dev:type><maml:name>Int32</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>1</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="sleep"><maml:name>Interval</maml:name>
<maml:Description><maml:para>How much time to sleep in seconds between each test. Maximum is 60. You may want to use a sleep interval to mitigate possible caching effects.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Double</command:parameterValue>
<dev:type><maml:name>Double</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>0.5</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="ie"><maml:name>IncludeExpression</maml:name>
<maml:Description><maml:para>Include the test scriptblock in the output.
</maml:para>
</maml:Description>
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>AsJob</maml:name>
<maml:Description><maml:para>Run the tests as a background job.
</maml:para>
</maml:Description>
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="min"><maml:name>RandomMinimum</maml:name>
<maml:Description><maml:para>You can also specify a random interval by providing a random minimum and maximum values in seconds.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Double</command:parameterValue>
<dev:type><maml:name>Double</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>0</dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="max"><maml:name>RandomMaximum</maml:name>
<maml:Description><maml:para>You can also specify a random interval by providing a random minimum and maximum values in seconds.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Double</command:parameterValue>
<dev:type><maml:name>Double</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>0</dev:defaultValue>
</command:parameter>
</command:parameters>
<command:inputTypes><command:inputType><dev:type><maml:name>scriptblock</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:inputType>
</command:inputTypes>
<command:returnValues><command:returnValue><dev:type><maml:name>Custom measurement object</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:alertSet><maml:alert><maml:para>Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/
</maml:para>
</maml:alert>
</maml:alertSet>
<command:examples><command:example><maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
<dev:code>PS C:\&gt; $cred = Get-credential globomantics\administrator
PS C:\&gt; $c = "chi-dc01","chi-dc04"
PS C:\&gt; Test-Expression {param ([string[]]$computer,$cred) get-wmiobject -class win32_logicaldisk -computername $computer -credential $cred } -argumentList $c,$cred
 
 
Tests : 1
TestInterval : 0.5
AverageMS : 1990.6779
MinimumMS : 1990.6779
MaximumMS : 1990.6779
MedianMS : 1990.6779
TrimmedMS :
PSVersion : 5.1.14409.1005
OS : Microsoft Windows 8.1 Enterprise</dev:code>
<dev:remarks><maml:para>Test a command once passing an argument to the scriptblock. There is no TrimmedMS value because there was only one test.
</maml:para>
</dev:remarks>
</command:example>
<command:example><maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title>
<dev:code>PS C:\&gt; $sb = {1..1000 | foreach {$_*2}}
PS C:\&gt; test-expression $sb -count 10 -interval 2
 
Tests : 10
TestInterval : 2
AverageMS : 72.78199
MinimumMS : 29.4449
MaximumMS : 110.6553
MedianMS : 90.3509
TrimmedMS : 73.4649625
PSVersion : 5.1.14409.1005
OS : Microsoft Windows 8.1 Enterprise
 
 
PS C:\&gt; $sb2 = { foreach ($i in (1..1000)) {$_*2}}
PS C:\&gt; test-expression $sb2 -Count 10 -interval 2
 
Tests : 10
TestInterval : 2
AverageMS : 6.40283
MinimumMS : 0.7466
MaximumMS : 22.968
MedianMS : 2.781
TrimmedMS : 5.0392125
PSVersion : 5.1.14409.1005
OS : Microsoft Windows 8.1 Enterprise</dev:code>
<dev:remarks><maml:para>These examples are testing two different approaches that yield the same results over a span of 10 test runs, pausing for 2 seconds between each test. The values for Average, Minimum and Maximum are in milliseconds.
</maml:para>
</dev:remarks>
</command:example>
<command:example><maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title>
<dev:code>PS C:\&gt; Test-expression {Param([string]$computer) get-service bits,wuauserv,winrm -computername $computer} -count 5 -IncludeExpression -argumentList chi-hvr2
 
 
Tests : 5
TestInterval : 500
AverageMS : 15.53376
MinimumMS : 11.6745
MaximumMS : 24.9331
MedianMS : 13.8928
TrimmedMS : 13.6870666666667
PSVersion : 5.1.14409.1005
OS : Microsoft Windows 8.1 Enterprise
Expression : Param([string]$computer) get-service bits,wuauserv,winrm -computername $computer
Arguments : {chi-hvr2}</dev:code>
<dev:remarks><maml:para>Include the tested expression in the output.
</maml:para>
</dev:remarks>
</command:example>
<command:example><maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title>
<dev:code>PS C:\&gt; Test-Expression { get-eventlog -list } -count 10 -Interval 5 -asjob
 
 
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
184 Job184 RemoteJob Running True WIN81-ENT-01 ...
 
PS C:\&gt; receive-job 184 -keep
 
Tests : 10
TestInterval : 5
AverageMS : 2.80256
MinimumMS : 0.7967
MaximumMS : 14.911
MedianMS : 1.4469
TrimmedMS : 1.5397375
PSVersion : 5.1.14409.1005
OS : Microsoft Windows 8.1 Enterprise
RunspaceId : f30eb879-fe8f-4ad0-8d70-d4c8b6b4eccc</dev:code>
<dev:remarks><maml:para>Run the test as a background job. When the job is complete, get the results.
</maml:para>
</dev:remarks>
</command:example>
<command:example><maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title>
<dev:code>PS C:\&gt; {1..1000} | Test-Expression -count 10 -randomminimum 1 -randommaximum 10
 
Tests : 10
TestInterval : Random
AverageMS : 0.63899
MinimumMS : 0.2253
MaximumMS : 3.9062
MedianMS : 0.24475
TrimmedMS : 0.2823
PSVersion : 5.1.14409.1005
OS : Microsoft Windows 8.1 Enterprise</dev:code>
<dev:remarks><maml:para>Pipe a scriptblock to be tested.
</maml:para>
</dev:remarks>
</command:example>
</command:examples>
<command:relatedLinks><maml:navigationLink><maml:linkText>Online Version:</maml:linkText>
<maml:uri>https://github.com/jdhitsolutions/Test-Expression/blob/master/docs/Test-Expression.md</maml:uri>
</maml:navigationLink>
<maml:navigationLink><maml:linkText>Measure-Command</maml:linkText>
<maml:uri>http://go.microsoft.com/fwlink/?LinkId=821828</maml:uri>
</maml:navigationLink>
</command:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
<command:details><command:name>Test-ExpressionForm</command:name>
<command:verb>Test</command:verb>
<command:noun>ExpressionForm</command:noun>
<maml:description><maml:para>Display a graphical test form.
</maml:para>
</maml:description>
</command:details>
<maml:description><maml:para>This command will display a WPF-based form that you can use to enter in testing information. Testing intervals are in seconds. All of the values are then passed to the Test-Expression command. Results will be displayed in the form.
</maml:para>
<maml:para>When you close the form, the last result object will be passed to the pipeline, including all metadata, the scriptblock and arguments.
</maml:para>
</maml:description>
<command:syntax><command:syntaxItem><maml:name>Test-ExpressionForm</maml:name>
</command:syntaxItem>
</command:syntax>
<command:parameters></command:parameters>
<command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:inputType>
</command:inputTypes>
<command:returnValues><command:returnValue><dev:type><maml:name>System.Object</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:alertSet><maml:alert><maml:para>Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/
</maml:para>
</maml:alert>
</maml:alertSet>
<command:examples><command:example><maml:title>Example 1</maml:title>
<dev:code>PS C:\&gt; test-expressionform</dev:code>
<dev:remarks><maml:para>Launch the form.
</maml:para>
</dev:remarks>
</command:example>
</command:examples>
<command:relatedLinks><maml:navigationLink><maml:linkText>Online Version:</maml:linkText>
<maml:uri>https://github.com/jdhitsolutions/Test-Expression/blob/master/docs/Test-ExpressionForm.md</maml:uri>
</maml:navigationLink>
<maml:navigationLink><maml:linkText>Test-Expression</maml:linkText>
<maml:uri></maml:uri>
</maml:navigationLink>
</command:relatedLinks>
</command:command>
</helpItems>