Cycle-CLI (Command Line Interface) Execution

Cycle allows the ability to run a Feature File or Playlist from the command line. Combining this functionality with a Continuous Integration or Continuous Testing process allows for the execution of tests at a preset or recurring time.

To execute Cycle from the command line:

1. At the command prompt, navigate to the directory where the cycle-cli.exe file is located (typically C:\Program Files (x86)\CycleLabs\Cycle).

2. Run cycle-cli followed by any optional parameters, with the last parameter being the name of the Feature File or Playlist to be executed.

   • Note that if you are running cycle-cli from a machine where you do not also run the Cycle UI (such as in a CI/CD pipeline), you will need to use the --token argument to provide a valid token for authentication. It is recommended that this is injected as an environment variable for security. See the Obtaining a token section below for details.
   • By default, cycle-cli will look for a .cycuser file that matches the user that you logged into Cycle 2 with when you obtained the token. E.g., if you logged in as j.doe@cyclelabs.io, it will look for a j.doe.cycuser file. If you use a more generic .cycuser file in your pipeline to store settings required for your pipeline tests to run successfully, for example, jenkins.cycuser, you can use the -u (--user-profile) argument to specify the .cycuser file to use.

Example 1: cycle-cli --output-directory C:\Cycle\Output --project-file MyProject.cycproj webtest.feature

Example 2: cycle-cli --project-file MyProject.cycproj terminal.feature web.feature sql.feature This would run each of the three features sequentially.

Note: If your Feature includes steps that prompt the user, these steps will be skipped.

Obtaining a Token

Applicable for Cycle 2.14 and beyond

To obtain a token for use with cycle-cli, open the Cycle UI and navigate to Help > Copy Authentication Token. This will copy a token to your clipboard that you can then inject into your CI/CD pipeline as an environment variable.

Below are examples of running cycle-cli with the --token argument and with both the --token and -u (or --user-profile) arguments from PowerShell:

Authentication using Client Credentials OAuth2 Flow

This user manual provides step-by-step instructions for setting up and utilizing the Client Credentials OAuth2 Flow in the Cycle platform. This flow allows you to authenticate against your Cycle subscription independently within a pipeline, using client credentials instead of a token associated with a specific team member.

Step 1: Creating a Client

1. Log into the User Portal:

   • Open your web browser and navigate to the Cycle User Portal.
   • Enter your credentials to log in.

2. Access Application Secrets:

   • Once logged in, locate and click on the "Application Secrets" option in the user portal.

3. Create a New Client:

   • Within the Application Secrets section, find the "clients" section in the left pane.
   • Click on the "+" button next to the "clients" section.
   • A modal will appear prompting you to enter a client name of your choice.
   • Enter the desired client name and click "OK" to confirm.
   • After creating the client, Cycle Labs will still need to authorize the client with our identity provider before you can use it to authenticate with cycle-cli. Email help@cyclelabs.io with your new client name and ID before using it with cycle-cli. Do not send any client secrets in the email.

Step 2: Generating Client Secret

1. Adding Application Secret:

   • After creating the client, click on the "Add Secrets" button located in the top right corner of the screen.

2. Name Your Secret:

   • In the modal that appears, enter a name for your application secret.
   • Press "OK" to confirm.

3. Copy Your Secret:

   • Once the secret is generated, use the copy button provided to copy the generated secret.
   • Note: This is the only time you will have access to the secret in user management.

4. Securely Store Your Secret:

   • It is crucial to store the secret in a secure location, such as a Key Vault or password manager.
   • Ensure that only authorized personnel have access to this secret.

Step 3: Authenticating in Cycle CLI

1. Run Cycle 2:

   • When running Cycle 2 commands, you will need to use the Client ID (displayed next to the "Add Secrets" button in user management) and the client secret.

2. Using Cycle CLI:

   • When running cycle-cli commands, include the following arguments:
     • --clientid: Provide the Client ID associated with your client.
     • --client-credential: Enter the client secret obtained earlier.

3. Integration into Pipeline:

   • You can now authenticate against your Cycle subscription within a pipeline using client credentials.
   • Ensure that you inject your client secret as an environment variable into your pipeline job from your chosen secure storage (Key Vault or password manager).
   • Never hard-code your client secret into your pipeline code, as this poses a security risk.

By following these steps, you can successfully set up and utilize the Client Credentials OAuth2 Flow in the Cycle platform for secure authentication within your pipelines. If you encounter any issues or have further questions, please refer to the Cycle documentation or reach out to our support team for assistance.

Managing Your Secrets

In addition to creating application secrets, you also have the ability to manage them within the Cycle platform. This section outlines how to delete existing secrets and create new ones, as well as provides information on accessing hints and expiration dates for your secrets.

Deleting a Secret

1. Access Application Secrets:

   • Navigate to the "Application Secrets" section within the Cycle User Portal.

2. Locate Secret:

   • Scroll through the list of existing secrets to find the one you wish to delete.

3. Delete Secret:

   • Next to the secret you want to remove, click on the appropriate action button (often represented by a trash can or delete icon).

4. Confirmation:

   • Confirm the deletion when prompted. Please note that this action is irreversible.

Creating a New Secret

1. Access Application Secrets:

   • Follow the steps outlined in the previous section to navigate to the "Application Secrets" section.

2. Generate New Secret:

   • Click on the "+ New Secret" button or similar option, depending on the interface.

3. Name Your Secret:

   • Provide a name for the new application secret.

4. Save Secret:

   • After naming your secret, save it within the platform. The new secret will be generated and added to your list of application secrets.

Accessing Secret Information

1. Hint and Expiration Date:

   • In the list of application secrets, you will see a hint of the first three characters of each secret.
   • Additionally, the expiration date of each secret will be visible, providing you with information on when the secret will no longer be valid.

2. Hint Utilization:

   • The hint serves as a reference point to help identify each secret, especially if you have multiple secrets stored.

3. Expiration Date Awareness:

   • Be mindful of the expiration date of your secrets. If nearing expiration, it is recommended to generate a new secret and update your applications accordingly to ensure uninterrupted access.

By following these guidelines, you can effectively manage your secrets within the Cycle platform, ensuring security and access control over your application secrets. If you have any questions or require further assistance, please refer to the Cycle documentation or contact our support team for help.

Managing the Token in a Pipeline

Best practice would be to never hard-code your token into a pipeline job or other use of cycle-cli. Rather, it should be injected as a secret or environment variable.

If you are running cycle-cli in Jenkins, store the token as a secret or utilize the Credentials Plugin.

If you are running cycle-cli in an Azure DevOps pipeline, store the token as a secret variable or in Azure KeyVault.

Note that the token has a lifetime of 90 days from when it is generated. You will need to be sure to update the secret or environment variable regularly to avoid any disruption to your automation as a result of letting the token expire.

Running cycle-cli in Parallel

Applicable for Cycle 2.14 and beyond Cycle uses an embedded H2 database to store execution results for reporting. This embedded database creates files in your APPDATA directory with a .db extension. These files are deleted automatically when Cycle is gracefully shut down. To handle a situation where any .db files were orphaned due to a forcible quit of cycle, at start up Cycle will try to delete any unused .db files. This can lead to some challenges when trying to run multiple instances of cycle-cli in parallel, where one instance of cycle-cli attempts to delete the .db files used by another instance of cycle-cli on the same machine. To avoid this situation, cycle-cli now supports a --skip-initial-purge argument. When using this flag, cycle-cli will not attempt to delete any .db files at start-up, avoiding any potential conflicts between multiple instances of cycle-cli.

Required Parameters

Parameter	Description	Example
Feature or Playlist	Path to Feature File or Playlist	C:\path\to\feature\feature_name.feature or C:\path\to\playlist\playlist_name.cycplay

Optional Parameters

Parameter	Description	Example
--echo-settings	Echo the current settings to the console and exit	C:\Program Files (x86)\CycleLabs\Cycle>cycle-cli --echo-settings
--env-file	Load environment variables from a custom .env file	cycle-cli --env-file "path/to/.env" [files to run]
-e, --error-handling [arg]	Error Handling Strategy (examples below)	C:\Program Files (x86)\CycleLabs\Cycle>cycle-cli --error-handling ALL_TESTS [files to run]
-l, --log-level [arg]	Logging level	cycle-cli --log-level verbose [files to run]
--no-tick	Turn off time-elapsed update for steps	cycle-cli --no-tick [files to run]
-o, --output-directory [arg]	Report output directory	cycle-cli --output-directory C:\Cycle\Output [files to run]
-p, --project-file [arg]	Project directory (this must be a directory containing a .cycproj file). If the current directory is the project directory, then this argument is optional. Otherwise, it will be required.	cycle-cli --project-file C:\Cycle\MyProject [files to run]
--settings	additional settings as key value pairs	cycle-cli --settings ProduceLocalReport=true [files to run]
-s, --settings-file [arg]	Settings file location to override settings used in Cycle client	cycle-cli --settings-file C:\Cycle\settingsoverride.json [files to run]
--skip-initial-purge	Skip attempting to clean up internal DB files at startup. This can be useful when running multiple instanes of Cycle in parallel in a pipeline.	cycle-cli --skip-initial-purge [files to run]
-t, --tags [arg]	Tags to be executed. For multiple tags, use multiple flags.	cycle-cli --tags receiving --tags picking [files to run]
--token [arg]	Token for authentication (available since 2.14)	cycle-cli --token $TOKEN [files to run]
-u, --user-profile [arg]	An alternate .cycuser file to use when executing tests	cycle-cli -u jenkins.cycuser [files to run]
-x, --shutdown-timeout [int]	Forcibly terminate Cycle upon test completion (in seconds) (default -1)	cycle-cli -x 300 [files to run]
-h, --help	Show help message	cycle-cli --help
--version	Show Cycle version	cycle-cli --version

Error Handling Strategies

Features:

FEATURE = End Feature Execution

SCENARIO = Skip to next Scenario

Example: Cycle>cycle-cli --error-handling FEATURE palletpick.feature

Playlists:

NONE = Skip to next Scenario

SINGLE_TEST = Skip to next feature

ALL_TESTS = End Playlist Execution

Example: Cycle>cycle-cli --error-handling SINGLE_TEST listpick.cycplay

Group Tests:

NONE = Stop Failed Terminal

SINGLE_TEST = Stop Failed Group

ALL_TESTS = End Group Test Execution

Example: Cycle>cycle-cli --error-handling ALL_TESTS volumetest.cvt

Project File Parameter

This can be either the Project directory or the .cycproj file.

For example, a user has a Project in c:\users\MyUser\myproj... either c:\users\MyUser\myproj or c:\users\MyUser\myproj\myproj.cycproj would be acceptable arguments to follow the --Project-file parameter. This can be an absolute path or relative path. If this argument is not used, Cycle-CLI will look for a .cycproj file the current directory. So in command line, if the user cd's to MyUser\myproj, they would not have to use the --project-file argument.

Cycle-CLI results

When Cycle-CLI executes, the Step results are output to the command line. Steps that pass are output with a Pass and the number of ms they took to complete. Steps that failed are output with [Fail]. Cycle-CLI completes with the line Feature: Feature Name [Fail]/[Pass] - {number} ms.

Any of the reporting formats available to the main Cycle client can be generated if the respective settings are applied.

Replicating Settings

In many cases, Cycle-CLI is run on a different computer than Cycle itself. It is important for teams to carefully control what settings are in use when running Cycle-CLI. It is possible to replicate the needed settings by specifying a Project file for your Cycle-CLI execution. All of the pertinent execution settings will be included in the .cycproj file.

In addition to this, if there are a few specific settings that need to be overridden for a CycleCLI execution. They can be saved as "key":value pairs in valid json objects and loaded in for a given execution using the --settings-file parameter.