Test-Connection in PowerShell: Complete Guide to the Cmdlet

If you work with networks in Windows, Linux or macOS, sooner or later you're going to want to check if a host is responding and how healthy the path is. The Test-Connection cmdlet is the modern Swiss Army knife for ICMP pings, traceroute, MTU discovery, and TCP testing from PowerShell., with structured output that can be filtered and processed.

Furthermore, the cmdlet story has two sides: In classic Windows PowerShell (5.1) it relied on WMI and returned Win32_PingStatus, while in PowerShell 6 and later the cmdlet was redesigned and extended to be cross-platform and expose specific objects such as PingStatus, TraceStatus, or TcpPortStatus. Knowing both families of parameters and outputs allows you to diagnose thoroughly and accurately..

What is Test-Connection and what does it solve?

Test-Connection sends ICMP echo requests (ping) to one or more destinations and returns responses; it can also trace the route (traceroute), calculate the Path MTU, and test whether a TCP port is accessible. Compared to the traditional ping executable, The cmdlet returns rich objects that you can pipe, filter, and convert. to reports or dashboards.

In its modern version, the cmdlet adds parameters such as -Traceroute, -MtuSize, -TcpPort, -Repeat, -TimeoutSeconds, -IPv4/-IPv6 and -Detailed (the latter since PowerShell 7.4 to break down TCP attempts). With -Quiet you can limit the output to booleans by destination for quick decisions in scripts.

In environments where you previously combined ping, tracert, nslookup or telnet, PowerShell provides native options to cover virtually all connectivity diagnostics from a single tool.. And if you prefer another approach, there is Test-NetConnection for combined network checks, but this article focuses on squeezing Test-Connection.

Key changes: Windows PowerShell 5.1 vs PowerShell 6/7

There are two clear stages in the evolution of the cmdlet. In Windows PowerShell 5.1 and earlier, the cmdlet uses WMI and returns Win32_PingStatus; exposes parameters such as -ComputerName, -AsJob, -DcomAuthentication, -Impersonation, -Protocol, -ThrottleLimit, -TimeToLive (TTL), and -WsmanAuthentication, among others.

With the jump to PowerShell 6+, The cmdlet was rewritten to be cross-platform and its API changed: -TargetName is now used (instead of -ComputerName), Ping/Repeat/Traceroute/MtuSize/TcpPort parameter sets appear, the outputs are specific types such as PingStatus, TraceStatus, PingMtuStatus or TcpPortStatus, and -TimeoutSeconds, -ResolveDestination and -Detailed (7.4) arrive for TCP.

This implies that, If you write portable scripts, you must detect the version and adjust parameters and processing. output. One option is to cover both worlds with conditional branches ($PSVersionTable.PSVersion.Major).

Modern Syntax and Parameter Sets (PowerShell 6+)

The cmdlet offers several sets of parameters that activate different modesHere's an overview of the main options:

• Default Ping: Test-Connection
• Repeat Ping: Test-Connection -Repeat
• traceroute: Test-Connection -Traceroute
• MtuSizeDetect: Test-Connection -MtuSize
• TcpPort: Test-Connection -TcpPort

In all modes, -TargetName is required and accepts DNS names or IPv4/IPv6 addressesThe default output in ping is a sequence of PingStatus objects, one per echo.

Classic Syntax (Windows PowerShell 5.1)

Other signatures are used in Windows PowerShell 5.1 environments., with -ComputerName as the central parameter and several WMI authentication options:

• Default: Test-Connection
• Source: Test-Connection
• Quiet: Test-Connection

In this case, The default output is ManagementObject Win32_PingStatus, and with -AsJob a job object (System.Management.Automation.RemotingJob) is returned.

Modern parameters, explained one by one

-TargetName: Targets to test, supports IPv4/IPv6 names and addresses; position 0 and mandatory; accepts channeling by value and by property name.

-Ping: Forces ICMP ping mode; this is the default behavior, so it is usually ignored unless specifically combined.

-Repeat: sends pings continuously; If you provide multiple destinations, only repeat over the first one and skip the rest; incompatible with -Count in ping.

-Traceroute: Trace the route to the destination by returning TraceStatus objects per hop; from PowerShell 6 and supports -ResolveDestination for intermediate DNS names.

-MtuSize: detects the Path MTU to the destination, returning PingMtuStatus with the effective MTU size; useful in combination with -DontFragment and -BufferSize.

-TcpPort: attempts to open a TCP connection to the port specified on the destination; returns $true or $false (and with -Detailed in 7.4, TcpPortStatus objects with latencies and per-attempt information).

-Count: number of echo requests; by default 4 in ping and also valid with TcpPort.

-Delay: seconds between attempts; useful for congestion or sustained testing.

-BufferSize: payload bytes; 32 by default; set alongside -DontFragment for MTU testing.

-DontFragment: sets the no fragmentation flag on IP; key to Path MTU Discovery.

-IPv4 / -IPv6: force the IP protocol to be used; useful on dual-stack hosts or when there are resolution issues.

-MaxHops: maximum number of jumps allowed; 128 by default on Windows 10+.

-ResolveDestination: attempts to resolve the destination DNS name and, next to -Traceroute, also intermediate hosts if possible.

-Source: origin of shipment (equipment) when applicable; by default the local, useful in multi-origin scenarios.

-Quiet: suppresses errors and returns booleans by destination; $true if at least one ping arrives, $false if all fail.

-TimeoutSeconds: maximum waiting time for response; 5 seconds by default; available since PowerShell 6.

-Detailed: in TCP tests (-TcpPort), returns TcpPortStatus with Id, Direction, Latency, Connected and Status; built into PowerShell 7.4.

Classic Parameters and Options (Windows PowerShell 5.1)

-ComputerName: destinations to test; required and does not depend on PowerShell remoting.

-AsJob: runs the cmdlet in the background; returns a recoverable job object with Receive-Job so as not to block the session.

-DcomAuthentication: COM authentication level used with WMI; accepted values Default, None, Connect, Call, Packet, PacketIntegrity, PacketPrivacy, Unchanged (default Packet).

-Impersonation: WMI impersonation level; values Default, Anonymous, Identify, Impersonate, Delegate (by default Impersonate).

-Protocol: protocol for WMI; DCOM or WSMan depending on configuration.

-WsmanAuthentication: Authentication mechanism when using WSMan; supports Default, Basic, Negotiate, CredSSP, Digest, Kerberos.

-ThrottleLimit: maximum simultaneous connections for the command; by default 32.

-TimeToLive (TTL): maximum number of resends before discarding the packet; 128 by default on Windows (alias TTL).

-Source and -Credential: to send pings from other sources with appropriate credentials, especially useful for comparing latency from different locations.

Practical examples with PowerShell 6/7

Basic IPv4 ping to a specific server and analysis of the PingStatus output:

Test-Connection -TargetName Server01 -IPv4

Ping multiple destinations in a single command with array of names:

Test-Connection -TargetName Server01, Server02, Server12

Customize count, delay, hops and buffer size when the network is loaded:

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

Run as background job Reading destinations from a file and waiting for results:

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

Create a PSSession only if there is connectivity at least in an echo:

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

Discover the route with traceroute and return TraceStatus per hop:

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

Detailed TCP Test (PowerShell 7.4) for a typical TLS port:

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

Practical examples with Windows PowerShell 5.1

Simple ping to a remote computer with Win32_PingStatus output:

Test-Connection -ComputerName Server01

Ping multiple servers from the home team:

Test-Connection -ComputerName Server01, Server02, Server12

Ping a destination from multiple sources with credentials to compare latencies:

Test-Connection -Source Server02, Server12, localhost -ComputerName Server01 -Credential (Get-Credential)

Customize intents, TTL, buffer, and concurrency in extensive networks:

Test-Connection -ComputerName Server01 -Count 3 -Delay 2 -TTL 255 -BufferSize 256 -ThrottleLimit 32

Run as background job and collect results when finished:

$job = Test-Connection -ComputerName (Get-Content 'Servers.txt') -AsJob
if ($job.JobStateInfo.State -ne 'Running') {
  $results = Receive-Job $job
}

Ping with credentials and impersonation adjusting the level of impersonation:

Test-Connection Server55 -Credential (Get-Credential) -Impersonation Identify

Use boolean output for quick decisions in scripts:

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

Cmdlet inputs and outputs

Starters: In the modern version, objects are not piped directly to the cmdlet; Standard parameter values are accepted (TargetName supports piping by value or by property name.)

Outputs in PowerShell 6/7:

• Microsoft.PowerShell.Commands.TestConnectionCommand+PingStatus: one object per ICMP response.
• Microsoft.PowerShell.Commands.TestConnectionCommand+TraceStatus: one object per hop with -Traceroute.
• Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus: with -MtuSize for Path MTU.
• Boolean: with -Quiet or -TcpPort (arrays if there are multiple destinations).
• Microsoft.PowerShell.Commands.TestConnectionCommand+TcpPortStatus: with -Detailed for TCP in 7.4.

Outputs in Windows PowerShell 5.1:

• ManagementObject (Win32_PingStatus): for each echo.
• Boolean: when using -Quiet.
• System.Management.Automation.RemotingJob: if run with -AsJob.

Cross-platform notes and features

Linux and permissions: when using -BufferSize other than 32 or combinations with -MtuSize that change the default size, sudo may be requiredIn that case, the cmdlet throws an exception indicating that privileges are required.

Quiet and error handling: -Quiet returns booleans and removes errors; remember that with several destinations the exit is a matrix of values in order of evaluation.

Repeat vs Count: don't mix -Repeat with -Count in ping; -Repeat ignores additional destinations and only iterates over the first one. For multiple destinations with repetition, invoke the cmdlet for each one.

Resolve names: -ResolveDestination adds DNS resolution of the destination, and with -Traceroute, try to solve each jump; useful for mapping intermediate devices.

Compatibility: if you script should work on Windows PowerShell 5.1 and PowerShell 6/7, detects the version and uses -ComputerName or -TargetName accordingly, and adjusts the interpretation of the output.

Test-Connection and its relationship with Test-NetConnection

Before Test-NetConnection, utilities such as ping, tracert, nslookup or telnet were combined to diagnose connectivity. With PowerShell v4 came Test-NetConnection, which centralizes ICMP and TCP tests and even traces routes with a single cmdlet.

Still, Test-Connection covers deep scenarios with more specific objects for ICMP, MTU, traceroute, and modern TCP tests. You can complement it with Test-NetConnection when you need a quick all-in-one check.

Test-NetConnection Examples to compare behaviors:

# Chequeo general con más detalle
Test-NetConnection -InformationLevel Detailed

# Comprobar resolución y ruta hacia un host
Test-NetConnection -ComputerName google.com
Test-NetConnection -ComputerName google.com -TraceRoute

# Verificar un puerto TCP conocido
Test-NetConnection -ComputerName google.com -CommonTCPPort HTTP

# Especificar un puerto concreto
Test-NetConnection -ComputerName google.com -Port 80

In scenarios where telnet is no longer present by default, These PowerShell cmdlets simplify checking TCP ports and ICMP connectivity, adding useful metadata such as output interface or source address.