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 your 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 white list 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. Well, with the Functionize CLI you 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.
Installation
The Functionize CLI is available for Windows and macOS/Linux.
Download the installer here.
Follow our detailed installation guide here.
Logging in / Authentication
Logging in to the Functionize CLI takes place via authentication tokens. You must be authenticated in order to access and run your projects, tests, orchestrations, etc. Each token expires after one hour, so periodically you will need to generate a new token.
Run 'fze token generate' in order to generate a new token when you open the Functionize CLI.
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.
Getting Started
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 'fze -h' to view the main menu of Usage, Commands, and Flags.
Main Objects
Usage:
| fze [flags] | fze --debug |
| fze [command] | fze project |
Available Commands:
| Browser | Manage the browsers in which your tests will run |
| Env | Manage the Environments you have available for testing |
| Help | Help menus containing the Usage, Commands, and Flags for each object in the Functionize CLI |
| Job | Manage your NLP tests |
| Orchestration | Manage the Orchestrations you have for NLP or Architect tests |
| Project | Manage your testing Projects |
| Test |
Manage your 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 your team |
Flags:
| -a, --author string | Functionize Inc, ALL Rights Reserved |
| --config string | Configuration YAML file. Read more in the Installation Guide. |
| -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?
You can run every test in the Functionize CLI that you would be able to run in the main Functionize interface or in the API.
Find the Project ID by running fze project list -e {name of environment}
Find the test you wish to run by running fze test list -e {name of environment} -p {project ID}
Execute the test by running 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 and the URL to be tested.
Run 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. Read our detailed Tunnel Instructions here.
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 interface.
Find the Deployment ID Via Functionize CLI
- Run fze orchestration list to see your entire list of orchestrations.
- Scroll up from the prompt to view the full listing. Each orchestration's name is found as the "title" value for each entry.
- 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 Dashboard
- Open the Orchestrations tab.
- Click the Actions button on the right side of any Orchestration. Select the API Calls option.
- In the API Calls window, see the Deployment ID in the string for the Run Orchestration call.
Copy the Deployment ID for the Orchestration you want to run found using either of the above methods. Now you can easily execute the Orchestration from the Functionize CLI. 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 this down:
- fze orchestration run - Base command for running the orchestration
- -i string - The ID of the Orchestration you wish to run where you fill in the Deployment ID in the place of the word "string"
- --config string - The name of your specific configuration YAML file if you are using one will go in the place of the word "string"
- -w - Wait for the Orchestration to finish
- -o string - Output the results in the format you prefer, either JUnit or JSON, and put your selection in the place of the word "string"
- -p string - The location of where you wish the output file to be stored. In our example we used "." in the place of the word "string" to indicate the current directory.
How do I integrate with Jenkins?
Pairing Continuous Integration with your functional tests is a great way to improve your build process and catch code errors quickly. Deploy your code to your testing environment and automatically run your Orchestration of regression tests. If your tests fail, the build fails and you can quickly find and correct the issue, then setting Jenkins to try the build again. Release your features with a higher degree of confidence knowing your code is being tested with every committed change.
- Open your Jenkins dashboard, Select "New Item."
- Enter a name for your item, Select "Freestyle project," Click OK.
- On the General Tab, scroll down to the Build section, Select "Execute Shell" from the "Add build step" menu.
- In the Execute shell command test box enter:
touch {your YAML config file name}
rm {your YAML config file name}
echo "clientId: {your Client ID from the YAML file} \nclientSecret: {your Client Secret from the YAML file}" >> {your YAML file name}
fze token generate --config {your YAML file name}
fze orchestration run --wait --output junit --location . --id {Orchestration deployment ID} --config {your YAML file name} - Scroll down to the Post-build Actions section, Select Publish JUnit test result report from the Add post-build action menu. Enter your desired file name for the result report (e.g. "result.junit"), Click Save.
- Select Build Now on the left in the Jenkins project window. You can view the results by clicking the build number in the lower left and selecting Console Output. The results will also display in the Orchestrations page of the Functionize GUI.
How do I set up Orchestration notifications in Slack?
You can receive notifications in Slack when your Orchestrations execute. This is especially helpful if you set up a CI/CD integration as detailed above so the Jenkins build completion will trigger the notification to Slack.
- Within Slack, Create a channel to receive your notifications. Then click the + to open the App Directory. Select your Slack Workspace and click "Build" in the upper right. Click "Your Apps" and then click "Create New App."
- Select "From Scratch", provide a name and the Workspace, then click "Create App."
- On the Basic Information screen select "Incoming Webhooks." Activate Incoming Webhooks and click "Add New Webhook to Workspace." Select the channel created above for your notifications, click "Allow." Copy the Webhook URL.
- In the Functionize GUI open the Orchestrations page and click "Create New Orchestration."
- Name the Orchestration and select the Project(s), Tests, and other information in the Details tab.
- Select the Integrations tab, paste the Slack Webhook URL from above and enter the channel name.
- Select the Advanced tab and choose your preferred notifications with the Alerts Delivery menu (Alert sent on Failure only, Alert sent on all runs, No Alerts Sent).
- Click "Add New," confirm the correct test cases and click Submit.
When you execute the Orchestration you will receive an alert to Slack based on your notification preference. Clicking on the run Report in Slack will open the Orchestration results in Functionize.