HyperExecute CLI - Run test on HyperExecute

HyperExecute CLI is a command line interface that is required to run tests on HyperExecute. This page outlines all you need to know about the CLI and also explains about the different flags & functionalities supported by the HyperExecute CLI.

Download the HyperExecute CLI

You can download the HyperExecute CLI for your OS from the links given below :

Platform	Download Link
Linux	https://downloads.lambdatest.com/hyperexecute/linux/hyperexecute
Windows	https://downloads.lambdatest.com/hyperexecute/windows/hyperexecute.exe
macOS	https://downloads.lambdatest.com/hyperexecute/darwin/hyperexecute

HyperExecute CLI Supported Flags

HyperExecute CLI provides different command-line flags that let you control the HyperExecute platform as per your customised requirements. You can run hyperexecute.exe --help on your terminal to explore the different flags.

The various flags that are supported are listed below.

Flags	Type	Description
--concurrency	Numerical	Indicates the number of concurrent sessions on HyperExecute.
--config	string	Custom location for hyperexecute.yaml.
--download-artifacts	NA	Download the artifacts for a job.
--download-artifacts-path	string	Path of the directory to download artifacts for a job
--download-artifacts-zip	NA	Download the artifacts for a job as a zip.
--download-logs	NA	Downloads console logs of your every tests of a job.
--download-report	NA	Whether reports have to be downloaded or not.
--force-clean-artifacts	NA	Download the updated artifacts of your job.
-h, --help	NA	Help for hyperexecute.
--job-secret-file	string	Enter your secrets file path
-k, --key	string	LambdaTest Access Key.
--labels	string	Incorporates the labels in your job.
--no-track	NA	Stops updating the progress of the uplodaed jobs.
--preserve-payload	string	Preserves the job payload after its successful completion.
--runson	string	(comma-separated values of) OS on which the tests should run.
-s --scan	NA	Runs the network logs
--server-port	string	Port number for the server (default "9191")
-t, --target-directory	string	Directory where the test script has to be uploaded.
--target-path	string	Upload the files and folders as part of the suite payload.
--tests-per-tunnel	INT	Run the number of tests via tunnel.
-z, --use-zip	string	Path of the zip file that needs to be uploaded.
-u, --user	string	LambdaTest username.
--vars	string	Method used to name keys.
--verbose	NA	Logging of every proxy request to stdout.
--version	NA	Version of the HyperExecute CLI.

--concurrency

This flag allows you to define the number of concurrent sessions running on HyperExecute. For more information on concurrency, go to this page.

--concurrency 2

---

--config

This flag allows you to enter a custom location where you can download the HyperExecute YAML file. To learn more about the HyperExecute YAML, visit this page.

--config "/home/users/work/yaml/"  

---

--download-artifacts

This flag allows you to download all the test related results that are generated by your testing framework. You can use this key if you want to download the artifacts.

./hyperexecute --user undefined --key undefined --config RELATIVE_PATH_OF_YOUR_YAML_FILE --download-artifacts

note

• For Espresso with private devices HyperExecute can download user generated artefacts.

--download-artifacts-path

In case you want the artifacts to be downloaded to a specific directory, please provide the exact path followed by the flag as shown in the example below.

./hyperexecute --user undefined --key undefined --config RELATIVE_PATH_OF_YOUR_YAML_FILE --download-artifacts-path "PATH_OF_YOUR_SPECIFIED_DIRECTORY"

--download-artifacts-zip

If you want to download the zip file of the artifacts for a job.

./hyperexecute --user undefined --key undefined --config RELATIVE_PATH_OF_YOUR_YAML_FILE --download-artifacts-zip

---

--download-logs

This flag allows you to download the detailed console logs of your entire job including your individual tests and your pre and discovery phase.

---

--download-report

This flag allows you to download all the test related results that are generated by your testing framework. You can use this key if you want to download the reports.

---

--force-clean-artifacts

This flag will download the new artifacts of your job and will store it into the artifacts folder. If you have previously downloaded artifacts, it will be renamed as artifacts-old.

---

-h, --help

You can run this command if you need any help in understanding the definition of the flags on the CLI itself. However, if you need any further assistance we're just a ping away.

--help

---

--job-secret-file

• This flag allows you to specify the Secrets file containing the necessary secrets (credentials, API keys, ) for a particular job.

• The contents of this file will be accessible only within the scope of that specific job execution, enhancing security and streamlining secret management.

• This eliminates the need to store secrets on the service account and prevents their accidental exposure through the --vars flag.

--job-secret-file <RELATIVE_PATH_OF_YOUR_SECRET_FILE>

Sample Secret File

secretFile.txt

secret1=value1
secret2=value2

info

The secrets file contains highly sensitive information and must be strictly excluded from public exposure. Here's how to ensure its security:

Store Outside the Repository (Recommended)

• Store the secrets file in a location outside your project repository altogether. This method is more secure as it automatically gets excluded from your code scripts zip file.

Exclude from Version Control

• Adding the relative path of the file (in which you have stored your secret data) to your .gitignore or .hyperexecuteignore file. This prevents accidental inclusion of the file in your code repository.

---

-k, --key

The access key of your LambdaTest account. To find out how to retrieve your access key, visit this page.

--key undefined

---

--labels

This flag allows you to pass the labels of your Job.

--labels "testing"

---

--no-track

You can track the progress of your uploaded jobs with HyperExecute. However, this flag allows you to opt out of receiving those updates.

--no-track

---

--preserve-payload

This flag allows you to preserve the job payload after the job is completed successfully.

--preserve-payload

---

--runson

This flag overrides the defined OS value in your YAML file's runson flag. You can also define multiple values for OS (comma separated) in the case of Matrix and Hybrid mode execution.

In case of AutoSplit mode:

--runson linux

In case of Matrix or Hybrid mode:

--runson linux,win,win11,mac,mac13

---

-s, --scan

This flag runs the network logs in your local machine console .

--scan

---

--server-port

The --server-port flag is used to specify the port number that the HyperExecute server will use for communication. This can be useful if you need to run the server on a specific port due to network configurations or to avoid port conflicts with other applications.

--server-port=8080

---

-t, --target-directory

The targetDirectory option in the HyperExecute CLI specifies the directory where the output of the executed command will be stored. If this option is not specified, the output will be stored in the current working directory.

--target-directory "/home/users/work/yaml/scripts/"

---

--target-path

The target-path flag allows you to selectively upload specific files and folders as part of the suite payload. This can be used for streamlining the uploading process and ensuring that only relevant files are included in the payload. It can also be useful if a user wants to run tests in a monorepo for multiple services.

--target-path "src/test-suite/**"

---

--tests-per-tunnel

This flag allows you to run a certain number of tests via tunnel. The default maximum number of tests is 10.

--tests-per-tunnel 5

---

-z, --use-zip

This flag allows you to indicate the path of the zip file that needs to be uploaded for your tests to run. Let's say you already have a zipped payload that you want to upload, so you can provide the path of that payload and upload it.

Whenever you zip your test files, it creates a folder, let's say tests.zip. Now, when this zip folder is unarchived, HyperExecute searches for a file named .hyperexecute.yaml, which should be present in the root folder only.

In another scenario, suppose you first created a folder. Inside that folder, you put all your required test files and then zip that folder (say folder.zip). When this zip folder is unarchived, HyperExecute will again search for the .hyperexecute.yaml file, which in this case won't be available as it will be inside the folder, which will throw an error.

--use-zip "/home/users/work/yaml/zip/"

---

-u, --user

The username of your LambdaTest account.

--user undefined

---

--vars

This method allows you to name your variables. It helps you optimize the content of your YAML file by allowing for more flexibility.

You can specify the email address for sharing reports or artifacts in a YAML configuration file using a variable. This allows you to dynamically set the email address and pass it via CLI, providing more flexibility than hardcoding the email address in the YAML file. Learn about this in detail.

--vars "org=Lambdatest" --vars "product=HyperExecute" --vars "email=xyz@abc.com" --vars "email1=abc@xyz.com"

---

--verbose

This flag allows you to log all of your proxy requests to the output section (stdout).

--verbose 

---

--version

This flag indicates the version of HyperExecute CLI binary that you are running on your system.

--version 

---

analyze

This flag runs HyperExecute Analyze, which is a language and environment detection tool used to render every language and framework detail the user has in his project, which includes finding private dependencies.

hyperexecute analyze

---

Trigger your Test from HyperExecute CLI

In order to trigger your job on HyperExecute, execute the following command in your terminal. You will need to insert the name of your YAML file in place of the RELATIVE_PATH_OF_YOUR_YAML_FILE before running this command.

./hyperexecute --user undefined --key undefined --config RELATIVE_PATH_OF_YOUR_YAML_FILE 

tip

In case of macOS, if you get a permission denied warning while executing CLI, simply run chmod u+x ./hyperexecute to allow permission. In case you get a security popup, allow it from your System Preferences → Security & Privacy → General tab.

note

If you're running on a minimal alpine image, please make sure to install essential linux dependencies for HyperExecute CLI to work. (An example with our sample repo has been given below):

apk add libc6-compat git bash
git clone https://github.com/LambdaTest/behave-selenium-hyperexecute-sample.git
cd behave-selenium-hyperexecute-sample/
wget https://downloads.lambdatest.com/hyperexecute/linux/hyperexecute
chmod +x hyperexecute
./hyperexecute --user <lt_user> --key <lt_access_key> --config yaml/win/behave_hyperexecute_autosplit_sample.yaml

Running HyperExecute CLI in Quiet Mode

Each time a job is run in Hyperexecute, a large number of logs are produced. These logs are sometimes beneficial for thorough debugging and analysis, it occasionally overwhelms Continuous Integration (CI) systems with an excessive amount of logs, especially when handling a large number of test executions.

Hyperexecute provides a "Quiet mode" as a solution to this issue and to give users more control over the logging output. By only displaying significant updates during the test execution, this enables you to run tests with less logs.

To enable the Quiet Mode, you need to paas these commands in your terminal and then trigger the command to execute your job.

Linux / macOS

env | grep CI # Used to check if the CI variable is set to true or not
export CI=true # If it's not set to true, then use this command to set as true

Windows

env | grep CI # Used to check if the CI variable is set to true or not
set CI=true # If it's not set to true, then use this command to set as true

Output

📕 Use the HyperExecute CLI's Frequently Asked Questions to gain more knowledge about it.