Test-Connection | Taking on PowerShell one cmdlet at a time | Weekly Blog

Share this post:

This is a part of an on-going blog series written by Adam Gordon. Each week, Adam will walk you through a PowerShell command, showing you when and how to use each one. This week, Adam covers Test-Connection. 

When to use Test-Connection?

The Test-Connection cmdlet sends Internet Control Message Protocol (ICMP) echo request packets, or pings, to one or more remote computers and returns the echo response replies. You can use this cmdlet to determine whether a particular computer can be contacted across an IP network.

You can use the parameters of Test-Connection to specify both the sending and receiving computers, to run the command as a background job, to set a time-out and number of pings, and to configure the connection and authentication.

Unlike the familiar ping command, Test-Connection returns a TestConnectionCommand+PingStatus object that you can investigate in PowerShell.

The –Quiet parameter returns a Boolean value in a System.Boolean object for each tested connection. If multiple connections are tested, an array of Boolean values is returned.

What version of PowerShell am I using for this blog?

Get the PowerShell Version from your machine:


This command shows you the PowerShell version information on your machine.

How to use Test-Connection?

Send echo requests to a remote computer:

Test-Connection -TargetName SCCMDC -IPv4

Test-Connection uses the -TargetName parameter to specify the SCCMDC computer. The -IPv4 parameter specifies the protocol for the test.

A series of TestConnectionCommand+PingStatus objects are sent to the output stream, one object per ping reply from the target machine.

Use parameters to customize the test command:

 Test-Connection -TargetName SCCMDC -Count 3 -Delay 2 -MaxHops 128 -BufferSize 256

Test-Connection uses the –TargetName parameter to specify SCCMDC. The –Count parameter specifies three pings are sent to the SCCMDC computer with a –Delay of 2-second intervals.

NOTE: You might use these options when the ping response is expected to take longer than usual, either because of an extended number of hops or a high-traffic network condition.

Run a test as a background job:

Line # 1:  $job = Start-Job -ScriptBlock { Test-Connection -TargetName (Get-Content -Path “C:\Test\Servers.txt”) }

Line # 2:  $Results = Receive-Job $job -Wait

The Start-Job command uses the Test-Connection cmdlet to ping computers. The value of the –TargetName parameter is a Get-Content command that reads a list of computer names from the Servers.txt file.

The command uses the Start-Job cmdlet to run the command as a background job and it saves the job in the $job variable.

The Receive-Job command is instructed to -Wait until the job is completed, and then gets the results and stores them in the $Results variable.



Create a session only if a connection test succeeds:

if (Test-Connection -TargetName SCCMDC -Quiet) { New-PSSession -ComputerName SCCMDC }

The Test-Connection cmdlet pings the SCCMDC computer, with the –Quiet parameter provided. The resulting value is $True if any of the four pings succeed. If none of the pings succeed, the value is $False.

If the Test-Connection command returns a value of $True, the command uses the New-PSSession cmdlet to create the PSSession.

Use the Traceroute parameter:

 Test-Connection -TargetName www.google.com -Traceroute

Introduced in PowerShell 6.0, the –Traceroute parameter maps a route between the local computer and the remote destination you specify with the –TargetName parameter.

Learn last week’s command: Get-AuthenticodeSignature.

Need PowerShell training? Check out ITProTV’s PowerShell online IT training courses.