Class TerminalActions

java.lang.Object
com.shaft.cli.TerminalActions
public class TerminalActions extends Object
Executes shell commands on local or remote terminals.

Supports local OS command execution via ProcessBuilder and remote command execution over SSH using JSch. Commands can be run synchronously or asynchronously with configurable timeouts.

Usage example: 

SHAFT.CLI.terminal().performTerminalCommand("ls -la");
See Also:

  • Constructor Details

    • TerminalActions

      public TerminalActions()
      This constructor is used for local terminal actions.

    • TerminalActions

      public TerminalActions(boolean asynchronous)
      This constructor is used for local terminal actions.
      Parameters:
      asynchronous - true for asynchronous execution of commands in a separate thread

    • TerminalActions

      @Deprecated(since="10.2.20260614", forRemoval=true) public TerminalActions(String dockerName, String dockerUsername)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Docker-wrapped terminal execution is deprecated for removal; use performTerminalCommand(String) on the host or target environment directly.
      This constructor is used for local terminal actions inside a docker.
      Parameters:
      dockerName - the name of the docker instance that you want to execute the terminal command inside
      dockerUsername - the username which will be used to access the docker instance. Must have the access/privilege to execute the terminal command

    • TerminalActions

      public TerminalActions(String sshHostName, int sshPortNumber, String sshUsername, String sshKeyFileFolderName, String sshKeyFileName)
      This constructor is used for remote terminal actions.
      Parameters:
      sshHostName - the IP address or host name for the remote machine you want to execute the terminal command on.
      sshPortNumber - the port that's used for the SSH service on the target machine. Default is 22.
      sshUsername - the username which will be used to access the target machine via ssh. Must have the access/privilege to execute the terminal command
      sshKeyFileFolderName - the directory that holds the ssh key file (usually it's somewhere in the test data of the current project)
      sshKeyFileName - the name of the ssh key file

    • TerminalActions

      @Deprecated(since="10.2.20260614", forRemoval=true) public TerminalActions(String sshHostName, int sshPortNumber, String sshUsername, String sshKeyFileFolderName, String sshKeyFileName, String dockerName, String dockerUsername)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Docker-wrapped terminal execution is deprecated for removal; use remote or local performTerminalCommand(String) without docker wrapping instead.
      This constructor is used for remote terminal actions inside a docker.
      Parameters:
      sshHostName - the IP address or host name for the remote machine you want to execute the terminal command on.
      sshPortNumber - the port that's used for the SSH service on the target machine. Default is 22.
      sshUsername - the username which will be used to access the target machine via ssh. Must have the access/privilege to execute the terminal command
      sshKeyFileFolderName - the directory that holds the ssh key file (usually it's somewhere in the test data of the current project)
      sshKeyFileName - the name of the ssh key file
      dockerName - the name of the docker instance that you want to execute the terminal command inside
      dockerUsername - the username which will be used to access the docker instance. Must have the access/privilege to execute the terminal command

  • Method Details

    • getInstance

      public static TerminalActions getInstance()

    • getInstance

      public static TerminalActions getInstance(boolean asynchronous)

    • getInstance

      public static TerminalActions getInstance(boolean asynchronous, boolean verbose)

    • getInstance

      public static TerminalActions getInstance(boolean asynchronous, boolean verbose, boolean isInternal)

    • getRemoteInstance

      public static TerminalActions getRemoteInstance(String sshHostName, int sshPortNumber, String sshUsername, String sshKeyFileFolderName, String sshKeyFileName)
      Creates a remote terminal actions instance that reuses the same SSH session for multiple command executions until quit() is called.
      Parameters:
      sshHostName - the IP address or host name for the remote machine
      sshPortNumber - the SSH service port on the target machine
      sshUsername - the username used to access the target machine
      sshKeyFileFolderName - the directory that holds the SSH key file
      sshKeyFileName - the SSH key file name
      Returns:
      a reusable remote TerminalActions instance

    • getRemoteInstance

      public static TerminalActions getRemoteInstance(String sshHostName, int sshPortNumber, String sshUsername, String sshKeyFileFolderName, String sshKeyFileName, boolean verbose)
      Creates a reusable remote terminal that optionally streams command output lines to discrete logs while the remote command is still running.
      Parameters:
      sshHostName - the IP address or host name for the remote machine
      sshPortNumber - the SSH service port on the target machine
      sshUsername - the username used to access the target machine
      sshKeyFileFolderName - the directory that holds the SSH key file
      sshKeyFileName - the SSH key file name
      verbose - when true, each output line is logged as it is read
      Returns:
      a reusable remote TerminalActions instance

    • isRemoteTerminal

      public boolean isRemoteTerminal()

    • isDockerizedTerminal

      @Deprecated(since="10.2.20260614", forRemoval=true) public boolean isDockerizedTerminal()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Docker-wrapped terminal execution is deprecated for removal.

    • performTerminalCommands

      public String performTerminalCommands(List<String> commands)

    • performTerminalCommands

      public String performTerminalCommands(List<String> commands, Map<String,String> environmentVariables)
      Executes one or more terminal commands with the supplied environment variables.

      For local terminals the variables are added to the spawned process environment. For remote terminals they are sent as SSH env requests, which only take effect when the SSH server allows them (for example via AcceptEnv in sshd_config); otherwise they are silently ignored by the server. Docker-wrapped terminal execution is deprecated and not extended for environment variables.

      Parameters:
      commands - the commands to execute
      environmentVariables - the environment variables to expose to the command
      Returns:
      the command output log

    • performTerminalCommand

      public String performTerminalCommand(String command)

    • performTerminalCommand

      public String performTerminalCommand(String command, Map<String,String> environmentVariables)
      Executes a terminal command with the supplied environment variables.
      Parameters:
      command - the command to execute
      environmentVariables - the environment variables to expose to the command
      Returns:
      the command output log
      See Also:

    • executeTerminalCommand

      public TerminalActions executeTerminalCommand(String command)
      Executes a terminal command and returns this terminal actions instance for fluent chaining.
      Parameters:
      command - the command to execute
      Returns:
      this TerminalActions instance

    • uploadFile

      public String uploadFile(String localFilePath, String remoteFilePath)
      Uploads a local file to the connected remote host over SFTP.

      Requires a remote terminal created through a remote SSH constructor or SHAFT.CLI.remoteTerminal(String, int, String, String, String). Docker-wrapped remote terminals are not supported; use performTerminalCommand(String) for file operations inside a container.

      Parameters:
      localFilePath - relative or absolute path to the local source file
      remoteFilePath - destination path on the remote host
      Returns:
      the remote destination path for assertions

    • downloadFile

      public String downloadFile(String remoteFilePath, String localFilePath)
      Downloads a file from the connected remote host over SFTP.
      Parameters:
      remoteFilePath - source path on the remote host
      localFilePath - relative or absolute destination path on the local machine
      Returns:
      the local absolute destination path for assertions

    • forwardLocalPort

      public String forwardLocalPort(int localPort, String remoteHost, int remotePort)
      Forwards a local port through the reusable SSH session to a remote host and port.

      Use 0 for localPort to let JSch assign an available local port. Active forwards are removed when quit() is called.

      Parameters:
      localPort - local bind port, or 0 for an ephemeral local port
      remoteHost - remote target host as seen from the SSH server
      remotePort - remote target port
      Returns:
      the bound local port as a string

    • forwardRemotePort

      public String forwardRemotePort(int remotePort, String localHost, int localPort)
      Forwards a remote port through the reusable SSH session to a local host and port.

      Remote port forwarding may require server-side SSH configuration. Active forwards are removed when quit() is called.

      Parameters:
      remotePort - remote bind port on the SSH server
      localHost - local target host as seen from the SSH client machine
      localPort - local target port
      Returns:
      the remote bind port as a string

    • getJschSession

      public com.jcraft.jsch.Session getJschSession()
      Returns the underlying JSch session for advanced remote terminal usage.

      Only available for reusable remote terminals created through SHAFT.CLI.remoteTerminal(String, int, String, String, String).

      Returns:
      the connected reusable JSch session

    • quit

      public void quit()
      Disconnects any reusable SSH session owned by this terminal actions instance.

      This method is safe to call before the first remote command is executed and is a no-op for local terminals or ephemeral remote terminals.