Test-Connection

Test-Connection
    [-TargetName] <string[]>
    [-Ping]
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-MaxHops <int>]
    [-Count <int>]
    [-Delay <int>]
    [-BufferSize <int>]
    [-DontFragment]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]

Test-Connection
    [-TargetName] <string[]>
    -Repeat
    [-Ping]
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-MaxHops <int>]
    [-Delay <int>]
    [-BufferSize <int>]
    [-DontFragment]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]

Test-Connection
    [-TargetName] <string[]>
    -Traceroute
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-MaxHops <int>]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]

Test-Connection
    [-TargetName] <string[]>
    -MtuSize
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]

Test-Connection
    [-TargetName] <string[]>
    -TcpPort <int>
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-Count <int>]
    [-Delay <int>]
    [-Repeat]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [-Detailed]
    [<CommonParameters>]

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.

This example sends echo request packets from the local computer to the Server01 computer.

Test-Connection -TargetName Server01 -IPv4

   Destination: Server01

Ping Source           Address                   Latency BufferSize Status
                                                   (ms)        (B)
---- ------           -------                   ------- ---------- ------
   1 ADMIN1           10.59.137.44                   24         32 Success
   2 ADMIN1           10.59.137.44                   39         32 Success
   3 ADMIN1           *                               *          * TimedOut
   4 ADMIN1           10.59.137.44                   28         32 Success

Test-Connection uses the TargetName parameter to specify the Server01 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.

This example sends pings from the local computer to several remote computers.

Test-Connection -TargetName Server01, Server02, Server12

This example uses the parameters of Test-Connection to customize the command. The local computer sends a ping test to a remote computer.

Test-Connection -TargetName Server01 -Count 3 -Delay 2 -MaxHops 255 -BufferSize 256

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

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.

This example shows how to run a Test-Connection command as a PowerShell background job.

$job = Start-Job -ScriptBlock { Test-Connection -TargetName (Get-Content -Path "Servers.txt") }
$Results = Receive-Job $job -Wait

The Start-Job command uses the Test-Connection cmdlet to ping many computers in an enterprise. 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.

This example creates a session on the Server01 computer only if at least one of the pings sent to the computer succeeds.

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

The Test-Connection cmdlet pings the Server01 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.

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.

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

   Target: google.com

Hop Hostname                  Ping Latency Status           Source       TargetAddress
                                      (ms)
--- --------                  ---- ------- ------           ------       -------------
  1 172.20.0.1                   1       4 Success          Lira         172.217.9.174
  1 172.20.0.1                   2       3 Success          Lira         172.217.9.174
  1 172.20.0.1                   3       2 Success          Lira         172.217.9.174
  2 12.108.153.193               1       3 Success          Lira         172.217.9.174
  2 12.108.153.193               2       3 Success          Lira         172.217.9.174
  2 12.108.153.193               3       2 Success          Lira         172.217.9.174
  3 12.244.85.177                1      11 Success          Lira         172.217.9.174
  3 12.244.85.177                2      12 Success          Lira         172.217.9.174
  3 12.244.85.177                3      12 Success          Lira         172.217.9.174
  4 *                            1      14 DestinationNetw… Lira         172.217.9.174
  4 *                            2       * TimedOut         Lira         172.217.9.174
  4 *                            3      20 DestinationNetw… Lira         172.217.9.174
  5 *                            1       * TimedOut         Lira         172.217.9.174
  5 *                            2      15 DestinationNetw… Lira         172.217.9.174
  5 *                            3       * TimedOut         Lira         172.217.9.174
  6 *                            1      18 DestinationNetw… Lira         172.217.9.174
  6 *                            2       * TimedOut         Lira         172.217.9.174
  6 *                            3      16 DestinationNetw… Lira         172.217.9.174
  7 *                            1       * TimedOut         Lira         172.217.9.174
  7 *                            2       * TimedOut         Lira         172.217.9.174
  7 *                            3       * TimedOut         Lira         172.217.9.174
  8 *                            1       * TimedOut         Lira         172.217.9.174
  8 *                            2       * TimedOut         Lira         172.217.9.174
  8 *                            3       * TimedOut         Lira         172.217.9.174
  9 *                            1       * TimedOut         Lira         172.217.9.174
  9 *                            2       * TimedOut         Lira         172.217.9.174
  9 *                            3       * TimedOut         Lira         172.217.9.174
 10 *                            1       * TimedOut         Lira         172.217.9.174
 10 *                            2       * TimedOut         Lira         172.217.9.174
 10 *                            3       * TimedOut         Lira         172.217.9.174
 11 172.217.9.174                1      23 Success          Lira         172.217.9.174
 11 172.217.9.174                2      21 Success          Lira         172.217.9.174
 11 172.217.9.174                3      22 Success          Lira         172.217.9.174

The Test-Connection command is called with the Traceroute parameter. The results, which are [Microsoft.PowerShell.Commands.TestConnectionCommand+TraceStatus] objects, are output to the Success output stream.

When you use the Detailed parameter, this cmdlet returns a detailed information about the status of the TCP connection attempts.

Test-Connection bing.com -TCPPort 443 -Detailed -Count 4

   Target: bing.com

Id Source     Address           Port Latency(ms) Connected Status
-- ------     -------           ---- ----------- --------- ------
 1 circumflex 2620:1ec:c11::200  443          12 True      Success
 2 circumflex 2620:1ec:c11::200  443          14 True      Success
 3 circumflex 2620:1ec:c11::200  443          17 True      Success
 4 circumflex 2620:1ec:c11::200  443          17 True      Success

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

You can't pipe objects to this cmdlet.

By default, this cmdlet returns a TestConnectionCommand+PingStatus object for each ping reply.

When you use the Traceroute parameter, this cmdlet returns a TestConnectionCommand+TraceStatus object for each ping reply along the route.

When you use the Quiet or TcpPort parameters, this cmdlet returns a Boolean value. If the cmdlet tests multiple connections, it returns an array of Boolean values.

When you use the MtuSize parameter, this cmdlet returns a TestConnectionCommand+PingMtuStatus object for each ping reply.

When you use the Detailed parameter, this cmdlet returns a TestConnectionCommand+TcpPortStatus object that shows the status of the TCP connection.

On Linux, using the BufferSize parameter or any combination of parameters with the MtuSize parameter set that results in a non-default buffer size of 32 bytes may require sudo. In those cases, Test-Command raises an exception with a message indicating that sudo is required.