Using the Functionize CLI

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.

Prerequisites

Setting up the Functionize CLI Tunnel requires a Proxy set for the user by the Functionize team. Message the Functionize Support team with your static public 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.

Download & Install the Functionize CLI

The Functionize CLI is available for Windows, Linux, and macOS.

Download the CLI installer here.

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 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 Windows

1. Extract the installer zip file
2. Run the install.exe file
   1. You will get an error that the file may be dangerous, or is unverified. In this case, click on More Options and Install/Run anyway
   2. If the Install/Run anyway is not available, please contact your system administrator, most likely there is a GPO enabled to block this type of installation.
3. Follow the installation wizard:
   1. Client ID: Can be found by clicking on your username > API Keys
   2. Client Secret:  Can be found by clicking on your username > API Keys
   3. Functionize Endpoint: This is optional, do not enter anything if using app.functionize.com
   4. Allow to download latest executable files from Functionize storage when we use fze tunnel init: Optional, defaults to Yes
   5. Support Internal Self-signed Certificates: Optional, default is yes
   6. Run as service: this is optional and only works if systemd is being used
   7. Enable debug mode: optional, default is no. If you set this to Yes, the log file path needs to be set and it needs to be valid!
   8. Your Endpoint: This is optional, it is only to be filled out in case you want a websockets tunnel. The value should be provided by the Functionize DevOps team, should be something like customer-name.vmcloud.functionize.com
   9. Number of Connections: This is optional. There should be no more connections then there are CPU threads in the VM.
   10. HTTPS Proxy: Optional, in case the customer need a proxy to reach the internet
   11. PAC file path: Optional if the customer uses PAC files in their environment
   12. Log file path: Optional, needed if the customer would like to see logs
   13. Select installation path.
4. If you have a tunnel that needs to run, click on Start, type in services.msc and click on the Services icon
5. Make sure FZETunnelService is in Running status and Startup Type is Automatic.

Installation for Linux

1. Extract the installer zip file from link above
2. Open a Terminal window
3. Navigate to the extracted zip file
4. Run the following command in the Terminal window: source install.sh
5. Follow the installation wizard:
   1. Client ID: Can be found by clicking on your username > API Keys
   2. Client Secret:  Can be found by clicking on your username > API Keys
   3. Functionize Endpoint: This is optional, do not enter anything if using app.functionize.com
   4. Your Endpoint: This is optional, it is only to be filled out in case you want a websockets tunnel. The value should be provided by the Functionize DevOps team, should be something like customer-name.vmcloud.functionize.com
   5. Number of Connections: This is optional. There should be no more connections then there are CPU threads in the VM.
   6. HTTPS Proxy: Optional, in case the customer need a proxy to reach the internet
   7. PAC file path: Optional if the customer uses PAC files in their environment
   8. Log file path: Optional, needed if the customer would like to see logs
   9. Allow to download latest executable files from Functionize storage when we use fze tunnel init: Optional, defaults to Yes
   10. Support Internal Self-signed Certificates: Optional, defaults to Yes
   11. Enable debug mode: optional, defaults to No. If you set this to Yes, the log file path needs to be set and it needs to be valid.
   12. Run as service: this is optional and only works if systemd is being used.
6. At this point, the CLI tool in installed, to start the tunnel, run the following commands:
   1. fze token generate
   2. fze tunnel init
   3. fze tunnel start

Installation for macOS

1. Extract the installer zip file from link above
2. Open a Terminal window
3. Navigate to the extracted zip file
4. Run the following command in the Terminal window: source install.sh
5. The following result from the command will appear in the Terminal window: Installing Functionize CLI. Detected Mac(Linux) platform. Installation was successful
6. Please run the following command in the Terminal window to get started: fze -h
7. 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'
8. Click Cancel on the modal window explaining the untrusted status
9. Open System Preferences > Security & Privacy and click Allow Anyway
10. Return to the Terminal window and run the following command again: fze -h
11. A pop-up will open to confirm you want to open an app from an unidentified developer, click Open
12. The Functionize CLI Help library will appear with the main list of available Commands and Flags
13. Configure the .yaml file with your Client ID and Client Secret, see below
14. Run the following command in the Terminal window to generate an authentication token: fze token generate

Configuration File

For macOS users, you must manually add your Client ID and Client Secret from the API Keys menu as well as your Functionize endpoint to the configuration .yaml file. You can use the default file .functionize-go-cli.yaml or you can create your own.

1. Use your preferred text editor to open the .yaml file.
2. Copy and paste the Client ID and Client Secret strings from the API Keys menu in Functionize.
3. Enter the Functionize endpoint.
   1. Note: Installation will default to 'app.functionize.com' if an option is not entered.
4. Save and quit your text editor.
5. Proceed to generating your authentication token.

Available options in the configuration file

• clientId: Client ID found in https://app.functionize.com/v1/profile/api-keys
• clientSecret: Client secret found in https://app.functionize.com/v1/profile/api-keys
• functionizeEndPoint: Optional, default is app.functionize.com
• endPoint: Provided by FZE DevOps, e.g. [customer-name].vmcloud.functionize.com
• noConnections: 4 (Optional, but should be set to at least 2. Do not set more connections then there are CPU threads.)
• proxy: IP and port of proxy
• non-proxy-hosts: Comma-separated values
• pacfile: Do not use this unless FZE provides the file
• logfile: Optional, default is to not to log. This is required if you set debugging.
• allowDownloadExecFiles: Optional, default is yes, do not change unless instructed specifically to do so.
• insecure: Optional, default is yes. This is to allow connections to applications with non-public certificates or self signed certificates.
• debug: Optional, default is no.
• logRotationInterval: Number of minutes between log rotations. Default is 15.
• logRotationRetention: Number of log files retained. Default is 5.

Installation for Kubernetes

The steps below provide a general guide for installing into Kubernetes. Please adjust them as needed to fit your environment.

1. Base64 Encode the Service Account Key: Functionize will provide an authentication file via email.
2. Create Kubernetes Secret for GCP Key: Use the base64 string to create a Kubernetes secret:
   • kubectl create secret generic gcp-key  --from-literal=key.json=<PASTE_BASE64_STRING_HERE>
   • Replace <PASTE_BASE64_STRING_HERE> with the actual base64 string from the json.b64 file that was sent over.
3. Configure Artifact Registry Authentication: Create a Kubernetes service account and link it to the Artifact Registry credentials:
   • kubectl create serviceaccount functionize-tunnel-sa
   • kubectl create secret docker-registry artifact-registry-creds --docker-server=us-central1-docker.pkg.dev  --docker-username=_json_key_base64 --docker-password="$(kubectl get secret gcp-key -o jsonpath='{.data.key\.json}' | base64 -d)"
   • kubectl patch serviceaccount functionize-tunnel-sa -p '{"imagePullSecrets": [{"name": "artifact-registry-creds"}]}'
4. Create Deployment File: Save the following as functionize-tunnel.yaml:
   • Note: Sample yaml file can be downloaded from here.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: functionize-tunnel
spec:
  replicas: 1
  selector:
    matchLabels:
      app: functionize-tunnel
  template:
    metadata:
      labels:
        app: functionize-tunnel
    spec:
      serviceAccountName: functionize-tunnel-sa
      containers:
      - name: functionize-tunnel
        image: us-central1-docker.pkg.dev/functionize-customer/tunnel/ws-tunnel:latest
        env:
        - name: FUNCTIONIZE_ENDPOINT
          value: "app.functionize.com"
        - name: TUNNEL_ENDPOINT
          value: "<CUSTOMER_PROXY_ENDPOINT>"
        - name: CLIENT_ID
          value: "<CUSTOMER_CLIENT_ID>"
        - name: CLIENT_SECRET
          value: "<CUSTOMER_CLIENT_SECRET>"
        # Optional
        - name: LOG_FILE
          value: "/var/log/logfile.log"
        - name: LOG_ROTATION_INTERVAL
          value: "720"
        - name: LOG_ROTATION_RETENTION
          value: "5"

• Apply the configuration: kubectl apply -f functionize-tunnel.yaml

5. Verify Deployment
   • Check pods: kubectl get pods -l app=functionize-tunnel
   • Check logs: kubectl logs -l app=functionize-tunnel

Installation in Docker

Authentication token will be created and sent by Functionize. To pull the image, the system downloading the image has to authenticate to the repository.

• Login to Artifact Registry was tested as follows:
  • cat <NAME_OF_KEY_FILE.json.b64> | docker login -u _json_key_base64 --password-stdin us-central1-docker.pkg.dev/functionize-customer
• Run the following: 
  • docker pull us-central1-docker.pkg.dev/functionize-customer/dbconnector/dbconnector:latest

Environment variables:

• FUNCTIONIZE_ENDPOINT : app.functionize.com
• TUNNEL_ENDPOINT : your proxy endpoint (FQDN provided by Functionize)
• CLIENT_ID : client ID (get from profile settings on app.functionize.com)
• CLIENT_SECRET : client Secret (get from profile settings on app.functionize.com)

Optional environment variables:

• LOG_FILE= /var/log/logfile.log #[any file within the container, DOESN'T have to mapped to a permanent location]
• LOG_ROTATION_INTERVAL=720 #[in minutes]
• ENV LOG_ROTATION_RETENTION=5 #[no of logs retained]

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 that 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!

Hardware Requirements

Functionize supports both Windows and Linux servers. Also, it’s important to understand how tunnels, cores, and tests are related. One tunnel connection is configured per core and runs a maximum of 6-10 tests in parallel. Note: You must allocate at least 1 core for OS functions on the small and medium and 2 cores on Large/x-large configurations.

Networking Requirements

You will need to allow access to the following FQDNs to enable the tunnel connection from the host. The host running the tunnel should be able to connect to:

• https://app.functionize.com over port 443
• https://www.functionizeapp.com over port 443
• wss://[customer].vmcloud.functionize.com over port 443  <== This will be provided by the Functionize DevOps team once the VM has been created.

Logging in / Authentication

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.

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 instructions, you get started by running the following command to view the main menu of Usage, Commands and Flags: fze -h

Main Objects

Usage

Available Commands

Flags

Commands for the Tunnel with the Functionize CLI

Available Commands:

Flags:

Starting and Stopping the Tunnel

Within the Functionize CLI, run the following commands:

1. Initialize the Tunnel connection: fze tunnel init
2. The following result from the above command should appear: Initializing tunnel. Tunnel has been successfully initialized.
3. Start the Tunnel connection: fze tunnel start --endPoint string
   Note: 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 int
   Note: 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.
4. Stop the Tunnel connection: fze tunnel stop
   Note: 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 Settings on the General tab.
• Proxy IP address and Port are added to the Test Settings on the Advanced tab.

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}
• Find the enabled browsers for a project by running command: fze project browsers -i {projectid}
• Execute the Test ID by running command: fze test run -b {Browser name} -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
  1. Run the following command to see your entire list of orchestrations: fze orchestration list
  2. Scroll up from the prompt to view the full listing and each orchestration's name is found as the Title value for each entry.
  3. The Orchestration Deployment ID is the string associated with the id label.
     Note: You want the value for id not for last_run_id
• Find the Deployment ID via Functionize UI
  1. Open the Orchestrations tab
  2. Click the Actions button on the right side of any Orchestration and select the API Calls option
  3. In the API Calls modal, see the &deploymentid in the string for the Run Orchestration call
• Execute orchestration via Functionize CLI
  1. Copy the Deployment ID for the orchestration to run found using either of the above methods
  2. 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 -i c5b2aa5cc41e7ff750625b11a937ea1d –config apiconfig.yaml -w -o junit –location . 

• 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 . to indicate the current directory.