The Functionize Command Line Interface (CLI) offers most of the functionality of our API endpoints as well as a few extra commands for easy CI/CD integration from a simple interface. The Functionize CLI also allows you to connect with external tools more easily.
Use the Functionize CLI to connect to non-public websites. This may be necessary if the application under test is only accessible with a special connection or runs locally. If so, the CLI supports a simple tunneling option to connect to a private site. This is much easier than setting up a whitelist for all our servers.
Use the Functionize CLI to integrate with CI/CD tools. Imagine if your CI/CD could execute your Functionize orchestrations and wait for the results before releasing new features. With the Functionize CLI users can build efficient multi-stage pipelines from Jenkins with a simple one line command. The Functionize CLI enables Functionize to seamlessly fit into any DevOps toolchain.
Learn more about the Functionize CLI from Installation to common use cases below.
Installing the Functionize CLI
The Functionize CLI is available for Windows and macOS/Linux.
Download the CLI installer here.
Authenticating to the Functionize CLI
Logging in to the Functionize CLI takes place via authentication tokens. You must be authenticated in order to access your projects and run tests, orchestrations, etc. Each token expires after one hour, so periodically you will need to generate a new token.
Run the following command in a terminal window to generate a new token when you open the Functionize CLI:
fze token generate
Note: When operating the Functionize CLI with a tunnel to a non-public site, it's important to remember that your token will expire after one hour unless your tunnel is still open. If the tunnel connection is live, the token will remain valid.
Installation Prerequisites
The Functionize CLI allows a user to connect with external tools more easily, such as Jenkins. The CLI is designed to work on both Windows and macOS/Linux machines. There are two core parts of the CLI:
- Tunnel setup: This allows a user to access local sites that are not publicly available over the internet
- Application commands: Functionize offers a robust set of command-line options to run tests, manage tests, create projects, users, and much more - these help you automate the usage of the application from systems such as CI/CD tools, onboarding tools, and more
API Credentials
Your Client ID and Client Secret will be required for configuration.
These can be found by opening the User menu and selecting API Keys from the main Functionize dashboard.
Installation for macOS/Linux
- Extract the installer zip file from link above
- Open a Terminal window
- Navigate to the extracted zip file
- Run the following command in the Terminal window: source install.sh
- The following result from the command will appear in the Terminal window:Installing Functionize CLI. Detected Mac(Linux) platform. Installation was successful
- Please run the following command in the Terminal window to get startedfze -h
- Functionize is not yet recognized as a 'Trusted Developer' - at this point a user will receive a message that the process was killed and will get a pop-up window about not opening files from 'Untrusted Developers'
- Click Cancel on the modal window explaining the untrusted status
- Open System Preferences > Security & Privacy and click Allow Anyway
- Return to the Terminal window and run the following command again:fze -h
- A pop-up will open to confirm you want to open an app from an unidentified developer, click Open
- The Functionize CLI Help library will appear with the main list of available Commands and Flags
- Configure the .yaml file with your Client ID and Client Secret, see below
- Run the following command in the Terminal window to generate an authentication token:fze token generate
Installation for Windows
- Extract the installer zip file
- Run the install.exe file
- Enter Client ID and Client Secret from the API Keys menu, see above, as well as the Functionize end point, if neededNote: Installation will default to 'app.functionize.com' - if an option is not entered. This bypasses the need to manually edit the configuration file as shown below.
- Follow the prompts in the installation wizard through to completion
- Open a Windows Command Line window
- Run the following command on the Command Line window: fze -h
- The Functionize CLI Help library with the main list of available Commands and Flags
- Run the following command on the Command Line window to generate the authentication token:fze token generate
Configuration File
For macOS and Linux users, you must manually add your Client ID and Client Secret from the API Keys menu, see above, as well as your Functionize end point to the configuration .yaml file. You can use the default file '.functionize-go-cli.yaml' or you can create your own.
- Use your preferred text editor to open the .yaml file
- Copy and paste the Client ID and Client Secret strings from the API Keys menu in Functionize
- Enter the Functionize end pointNote: Installation will default to 'app.functionize.com' - if an option is not entered.
- Save and quit your text editor
- Proceed to generating your authentication token
Using the Functionize CLI
Each object in the Functionize CLI follows the same format: Usage, Commands, and Flags.
- The Usage section shows how Commands and Flags can be combined to execute the function
- The Commands section displays each command available within that section as well as sub-commands for customization and setting proper configurations
- The Flags section offers your options for granular control of a command
Every command is documented within the Functionize CLI and can be accessed by adding:
-h or --help
to the end of your command. As noted in the Functionize CLI Installation Instructions, you get started by running the following command to view the main menu of Usage, Commands and Flags:
fze -h
Main Objects
Usage:
| fze [flags] | fze --debug |
| fze [command] | fze project |
Available Commands:
| Browser | Manage the browsers in which tests will run |
| Env | Manage the Environments available for testing |
| Help | Help menus contain the Usage, Commands, and Flags for each object in the Functionize CLI |
| Orchestration | Manage the Orchestrations for Architect tests |
| Project | Manage testing Projects |
| Test |
Manage tests built in Architect Note: Architect tests cannot be created via the Functionize CLI, but can be run, reviewed, etc. |
| Token | Manage the authorization tokens for logging in to the Functionize CLI |
| Tunnel | Manage the tunnel connections to your non-public test sites |
| User | Manage the users in a team |
Flags:
| -a, --author string | Functionize Inc, ALL Rights Reserved |
| --config string | Configuration YAML file. |
| -d, --debug | View the object in debug mode. By default this mode is off. |
| -h, --help | Help for every command. |
| -l, -license string | Name of license for the project. |
| -P, --prettyPrint | Receive JSON results in "Pretty print", easy-to-read formatting. By default this feature is on. |
| --viper | Use Viper configuration solution to simply process any configuration file format. By default this feature is on. |
Use Cases
Here are some common scenarios for using the Functionize CLI.
How do I run tests?
Users can run every test in the Functionize CLI that would be ran in the main Functionize UI or in the API.
Find the Project ID by running command:
fze project list -e {name of environment}
Find the Test ID to run by running command:
fze test list -e {name of environment} -p {project ID}
Execute the Test ID by running command:
fze test run -b {name of browser} -i {test ID}
How do I create a new Project?
When creating a new testing project via the Functionize CLI, you need two pieces of information:
- The Project's Name
- The URL to be tested
Run command:
fze project create -n {Name of project} -u {URL for project}
How do I test my non-public site?
We have provided a tunneling service via the Functionize CLI in order to test applications on private sites or running locally.
How do I see the results from running an Orchestration?
A background Orchestration does not automatically display detailed results for you to see when executed via the Functionize CLI. Below is an easy way to see those results and make them ready to use with a CI/CD solution, such as Jenkins.
First, let's look at two ways to find the Orchestration Deployment ID, the unique identifier for each Orchestration which is used for execution. This can be found in either the Functionize CLI or the main Functionize UI.
-
Find the Orchestration Deployment ID via Functionize CLI
- Run the following command to see your entire list of orchestrations:fze orchestration list
- Scroll up from the prompt to view the full listing and each orchestration's name is found as the Title value for each entry
- The Orchestration Deployment ID is the string associated with the id labelNote: You want the value for "id" not for "last_run_id"
-
Find the Deployment ID via Functionize UI
- Open the Orchestrations tab
- Click the Actions button on the right side of any Orchestration and select the API Calls option
- In the API Calls modal, see the '&deploymentid' in the string for the Run Orchestration call
-
Execute orchestration via Functionize CLI
- Copy the Deployment ID for the orchestration to run found using either of the above methods
- Now execute the orchestration from the Functionize CLI and to see detailed results from the orchestration, run the following command:fze orchestration run -i {Orchestration Deployment ID} --config {your YAML config file name} -w -o junit -p
Let's break down this Functionize CLI command:
- fze orchestration run – Base command for running the orchestration
- -i [string] – The ID of the orchestration to run, fill in the Deployment ID in place of "string"
- --config [string] – The name of your specific configuration YAML file, if using one, in the place of "string"
- -w – Wait for orchestration to finish
- -o [string] – Output results in preferred format, either JUnit or JSON, in place of "string"
- -p [string] – The location of where the output file is to be stored, in this example we used "." in place of "string" to indicate the current directory
Functionize CLI Tunnel
If an application under test is only accessible with a special connection or runs locally, a user may use the Functionize CLI to connect to non-public sites. The Functionize CLI supports a simple tunneling option to connect to a private site. This is much easier than setting up a whitelist for all our servers.
The Functionize CLI Tunnel is a secure reverse tunnel over secure websockets protocol (wss). The connection leverages the same token auth authentication as the rest of the Functionize CLI. The tunnel should require no changes to your firewall settings. DNS resolution takes place on the machine where the tunnel is started. You can also have more than one tunnel running in parallel.
Note: One limitation of the tunnel is the connection will sever if the computer goes to sleep. The authentication token generated for your Functionize connection will expire after 90 days if the tunnel is not open. The token will remain active if the tunnel itself remains open. In other words, don't let your tunnel machine go to sleep!
See below for a visual representation of the tunnel and how it communicates.
Setting up the Functionize CLI Tunnel requires a Proxy set for the user by the Functionize team. Message the Functionize Support team with your IP address and then they will provide you with the endpoint required to start the tunnel as well as the IP address and port to be used in your Test or Project Settings within Functionize, see below.
Commands for the Tunnel with the Functionize CLI
Available Commands:
| Init | Initialize the Tunnel connection. |
| Start | Open the Tunnel connection to your proxy domain. |
| Stop | Close the Tunnel connection, this may take up to 60 seconds if multiple connections are open. |
Flags:
| -e, --endPoint string | Set your remote endpoint with this flag - your Proxy domain is the string. |
| -h, --help | The list of Tunnel commands and flags. |
| --noConnections int | The number of parallel connections you wish to open, by default, one connection opens - you have the option of setting up to 12 parallel connections. |
Starting and Stopping the Tunnel
Within the Functionize CLI, run the following commands:
- Initialize the Tunnel connection:fze tunnel init
- The following result from the above command should appear:Initializing tunnel. Tunnel has been successfully initialized.
- Start the Tunnel connection:fze tunnel start --endPoint stringNote: The string is your Proxy endpoint provided to you from Support.Note: During the Start command you also have the option of setting the number of parallel connections with the flag--noConnections intNote: The int is the number of connections you wish to open, up to 12. By default, including not using this flag, one connection will open.
- Stop the Tunnel connection:fze tunnel stopNote: If multiple connections are open, it will take up to 60 seconds to disconnect. Also, as noted above, the Tunnel will remain open and active as long as the computer does not go to sleep.
Set the Proxy within your Project or Test
Proxy IP address and Port are added to the Project Advanced Settings on the Basic tab.
Proxy IP address and Port are added to the Test Settings on the Advanced tab.