API Fortress Command Line Tool

Welcome to the API Fortress Command Line Tool!

The tool itself: https://github.com/apifortress/afcmd/releases

The documentation for the API that that tool leverages:  https://apifortressv3.docs.apiary.io/

The tool, or rather, pair of tools, are designed to reduce the amount of legwork that goes into executing or uploading API Fortress tests. The following readme will explain each part of the process.

APFCMD allows a user to easily integrate API Fortress testing into other workflows. Example use cases are:

  • Executing API Fortress tests from a CI/CD tool
  • Incorporating API Fortress tests in a Git version control plan.
  • Pushing test code from an IDE to the API Fortress platform.

All of these scenarios, and more, can be accomplished with the tool.

Lets take a look at the two major components of the tool:

APIF-RUN

Run allows us to execute tests on the platform and do things with that data. We can run tests via API either in an authenticated or unauthenticated state. By passing credentials, we receive a more verbose test result. We can output this result to a file. We also have access to all of the standard options that API Fortress provides in its API (silent run, dry run, etc.)

RUN EXECUTION FLAGS

  • run-all – RUN ALL – This will execute all of the tests in a chosen project.
  • run-by-tag – RUN BY TAG – This will execute all tests with a selected tag (requires the -t flag to set tag)
  • run-by-id – RUN BY ID – This will execute a test with a specific ID (requires the -i flag to set id)
  • hook – HOOK – This is the webhook of the project you are working with. This can be either an API Fortress URL, or the key from a configuration file (set the path to the config file with the -c tag)

ex: to run all of the tests in a specific project, we would use the following command string:

python apif-run.py run-all http://mastiff.apifortress.com/yourWebHook

RUN OPTION FLAGS

  • -S – SYNC – This will provide a response body with the result of the test.
  • -f – FORMAT – This will determine the format of the test result output (JSON, JUnit, Bool). REQUIRES SYNC MODE (-S)
  • -d – DRY – This will cause the test run to be a dry run.
  • -s – SILENT – This will cause the test to run in silent mode.
  • -o – OUTPUT – This will write the result of the test to a local file. You must provide the path to the file to be created. Remember your filetype! (.json/.xml)
  • -c – CONFIG – This provides the path to a configuration file which can provide webhooks and user credentials. If no path is specified, the program will look for a config.yml in the same directory as it is (./config.yml)
  • -C – CREDENTIALS – This allows you to manually pass user credentials (username:password) (SUPERSEDES CONFIG FILE)
  • -t – TAG – This is how you pass a tag for RUN BY TAG mode.
  • -i – ID – This is how you pass an ID for RUN BY ID mode.
  • -e – ENVIRONMENT – This is how you pass environmental/override variables. The format is key:value. You can pass multiple sets of environmental variables like so: key:value key1:value1 key2:value2

APIF-PUSH

Push allows us to push tests into API Fortress. When tests are downloaded from the platform, they come as 2 XML files (unit.xml & input.xml). We can use this tool to push those files back to an API Fortress project, either individually or in bulk.

PUSH EXECUTION FLAGS

  • hook – HOOK – This is the webhook of the project you are working with. This can be either an API Fortress URL, or the key from a configuration file (set the path to the config file with the -c tag)

PUSH OPTION FLAGS

  • -p – PATH – This provides the path to the test file you wish to upload. You can pass multiple paths.
  • -r – RECURSIVE – This flag will make the call recursive; It will dive through the directory passed with -p and grab every test in all of its subdirectories.
  • -b – BRANCH – This allows you to specify a Git branch that these test files are attached to. Default is master.
  • -c – CONFIG – This provides the path to a configuration file which can provide webhooks and user credentials. If no path is specified, the program will look for a config.yml in the same directory as it is (./config.yml)
  • -C – CREDENTIALS – This allows you to manually pass user credentials (username:password) (SUPERSEDES CONFIG FILE)
  • T – TAG – This allows you to pass tags to be appended to the test after it is pushed. This will OVERWRITE ANY EXISTING TAGS. Multiple tags can be passed.
  • -t – ADD TAG – This will allow you to add additional tags to a test that already has tags attached.

CONFIGURATION FILE

A configuration file is a YAML file that is formatted as follows:

hooks:
  - key: cool_proj1
    url: https://mastiff.apifortress.com/app/api/rest/v3/A_WEBHOOK
    credentials:
      username: (your username)
      password: (your password)
  - key: uncool_proj
    url: https://mastiff.apifortress.com/app/api/rest/v3/ANOTHER_WEBHOOK
    credentials:
      username: (another username)
      password: (another password)
  - key: unauth_proj
    url: https://mastiff.apifortress.com/app/api/rest/v3/JUST_A_WEBHOOK_WITHOUT_CREDENTIALS
test_directory: /tests

Once you create a configuration file, you can pass the path with -c and the key to the data in place of the normal hook URL. If you also pass credentials, they’ll override the credentials in the configuration file. If you don’t include credentials in the config file, you can pass them manually or leave them out entirely.

EXAMPLES

Execute all of the tests in a project and output the results to a JUnit/XML file via an authenticated route:

python apif-run.py run-all http://mastiff.apifortress.com/yourWebHook -S -C my@username.com:password1 -f junit -o some/route/results.xml

Push all of the tests from a directory and all of its subdirectories to a project:

python apif-push.py http://mastiff.apifortress.com/yourWebHook -C my@username.com:password1 -r -p some/directory/with/tests

Execute one test in a project by ID, using a config file for credentials and webhook:

python apif-run.py run-by-id config_key -c path/to/config/file -i testidhash8924jsdfiwef891

NOTES

  • The order of the optional arguments passed does not matter.
  • Remember, in a bash environment, anything that has a space in it needs to be wrapped in quotes. This goes for paths, filenames, etc.

POST-RECEIVE SCRIPT FOR GIT

This Post-Receive script is meant to assist in the incorporation of API Fortress in your Git workflow. Dropping the file into the hooks directory of your .git file will cause newly committed API Fortress test code to be pushed to the API Fortress platform. The ‘test_directory‘ key in the config.yml will let the scripts know which folder the tests themselves are located in. It will then watch for commits from this folder and push the appropriate code to the platform.

Bamboo – Integrate API Tests & Results

Passing data from API Fortress to Atlassian Bamboo allows Bamboo users to include API Fortress test results in their CI/CD process.

Step 1: Generating a Webhook

The first step to integrating API Fortress into your CI/CD process is to grab the generated API hook for the project in question. To do so, head to the Settings panel in API Fortress. This view, seen below, can be accessed from anywhere in the application by clicking the Gear icon in the top right corner of the screen. Please note you need Manager access to generate a webhook. From Settings, click the API Hooks section and generate the hook for your project. The process can be seen in detail in the .gif below.

hook

Step 2: Select or Create a Bamboo Project

After we’ve created our webhook, calling it from within Bamboo is a fairly simple process. First, create a new project in Bamboo. You can also add to an existing project from this screen.

project

Step 3: Adding an HTTP Call

Next, we need to add an HTTP Call component and enter the webhook we generated. Depending on what you wish the call to API Fortress to trigger, you may append different routing on to the end of the webhook. The API Fortress API Documentation is located here.

httpcall

Step 4: Parsing Results

After the request is sent to the API Fortress API, we’ll need to save the JUnit data that’s returned. We do so by adding a JUnit Parser step.

junit

Once the above steps are completed and saved, the build sequence will make a call to API Fortress upon execution, receive the results of the tests, and parse the results.

summary

Integrate With Your CI/CD Platform (simple)

API Fortress was specifically built to make integrating with a CI/CD platform simple. Using our webhook you can execute API tests as part of your build and deployment flow, and get the results back in JSON or Junit format.

Step 1 – Install an HTTP Plugin

Depending on your CI/CD platform, you may need to install a plugin that allows for HTTP requests during the build process. API Fortress will need that to execute the tests.

Step 2 – Generate an API Hook

The first step to integrating API Fortress into your CI/CD process is to grab the generated API hook for the project in question. To do so, head to the Settings panel in API Fortress. This view, seen below, can be accessed from anywhere in the application by clicking the Gear icon in the top right corner of the screen. Please note you need Manager access to generate a webhook. From Settings, click the API Hooks section and generate the hook for your project.

The next step depends on what you’re trying to test. The following steps are going to assume that you wish to run all of the tests in a project. You can also run a single test, or a series of tests with a certain tag. If you would like to learn more about that please contact API Fortress.

As it stands, our API hook is as follows:
https://mastiff.apifortress.com/app/api/rest/v3/86f81b19-2d29-4879-91d9-6dbb2271fec0861

The normal command to run all of the tests in the project, per the API Fortress docs is /tests/run-all, so we append this on to the end of the API call. You may need to request JUnit output. To do that simply takes some query parameters. First, we need to set sync to true, and then we can set format to JUnit. In short, we need to append ?sync=true&format=junit to the webhook call. That gives us the final API call:
https://mastiff.apifortress.com/app/api/rest/v3/86f81b19-2d29-4879-91d9-6dbb2271fec0861/tests/run-all?sync=true&format=junit

Great! If we make this API call via a browser or a tool like Postman, we can see our results in JUnit. We’re almost there.

Step 3 – Execute HTTP Call From Your Platform

From your CI/CD platform’s dashboard, you’ll need to paste the webhook call to the flow. We have more specific docs, such as for Jenkins available.

The test results can then be passed along to platforms like qTest or Zephyr in your CI/CD pipeline.

Jenkins – Integrate Tests & Export Test Results to JUnit

Step 1 – Install Jenkins HTTP Plugin

Log in to your Jenkins account. First, click “Manage Jenkins,” then click “Manage Plugins.”

We’re going to need the HTTP Request plugin. To find the plugins, click the “Available” tab in the Plugins menu and use the filter in the top right corner to search for it.

Step 2 – Generate an API Hook

The first step to integrating API Fortress into your CI/CD process is to grab the generated API hook for the project in question. To do so, head to the Settings panel in API Fortress. This view, seen below, can be accessed from anywhere in the application by clicking the Gear icon in the top right corner of the screen. Please note you need Manager access to generate a webhook. From Settings, click the API Hooks section and generate the hook for your project.

The next step depends on what you’re trying to test. The following steps are going to assume that you wish to run all of the tests in a project. You can also run a single test, or a series of tests with a certain tag. If you would like to learn more about that please contact API Fortress.

To import our data into Jenkins as JUnit, we’ll export it in JUnit format using a query parameter. Since we already have our API hook, we just need to add the parameter to do so.

As it stands, our API hook is as follows:

https://mastiff.apifortress.com/app/api/rest/v3/86f81b19-2d29-4879-91d9-6dbb2271fec0861

The normal command to run all of the tests in the project, per the API Fortress docs is /tests/run-all, so we append this on to the end of the API call. We also need to request JUnit output via query parameters. First, we need to set sync to true, and then we can set format to JUnit. In short, we need to append ?sync=true&format=junit. That gives us the final API call:

https://mastiff.apifortress.com/app/api/rest/v3/86f81b19-2d29-4879-91d9-6dbb2271fec0861/tests/run-all?sync=true&format=junit

Great! If we make this API call via a browser or a tool like Postman, we can see our results in JUnit. We’re almost there.

Step 3 – Execute HTTP Call from Jenkins

From the Jenkins dashboard, let’s create a New Item. Next, we’re going to name and create a Freestyle Project. Click the OK button to proceed.

Scroll down the page until you see the “Add Build Step” pulldown menu. Select “HTTP Request.” This option will only be available if you installed the HTTP Request plugin in the previous step. We’re going to paste the API call we created above into the URL line. If we save this configuration, we can run the build and see Jenkins receive our JUnit test results in real time. These test results can then be passed along to platforms like qTest or Zephyr in a CI/CD pipeline.

Jenkins – Using The Plugin

The API Fortress Jenkins Plugin allows you to run tests during automated builds. The tests that fail can cause a build failure based on your Jenkins settings.

Watch the walkthrough video.

Install the Jenkins plugin

From the Jenkins Update Center, search and install the API Fortress plugin.

jenkins1A Jenkins restart may be required. You will be prompted accordingly.

Configure a build step

Add the API Fortress build step where it best suits your needs.

jenkins2

Modes

There are 4 testing modes available. “Run single test” will run a single test, while the others will run suites of tests.

Run Single Test

You can run a single test by providing a test ID. Test IDs can be found in test interstitial pages.

See where to retrieve the test IDs later in this document.

Run Automatch

You can run our “automatch” mode by providing a URL representing a certain endpoint. You can configure automatch patterns in the “Automatch” section of each test. Read more about automatch here .

Run by Tag

Choosing “by tag” will run multiple tests marked with a certain tag. Tags can be added and edited in the test details.

Run Project

By running a full project, you will be running all tests contained in the project.

Hook URL

The hook URL is an API endpoint that references a specific project within an API Fortress environment.

See the Hook URLs section to create one.

Options

The following options can apply to any mode.

Blocking

The plugin can silently run (blocking = false), which lets the build continue with a success and inform you if the test failed using the various methods available. Or it can actively determine the build success (blocking=true), so that the build will wait for the tests result and stop the build if the tests fail.

Dry-run

If checked, no events will be stored within API Fortress. To be used in conjunction with “blocking.”

Silent

If checked, no alerts will be sent if the tests fail.

Parameters Override

You can override up to 3 parameters in the test scope. These variables will appear within the test scope just like any other variable. This feature is useful if you are looking to override the domain of the service being tested (ie. staging vs production).

Hook URLs

Hook URLs are API endpoints representing one of your projects. These endpoints have unique paths, and do not require authentication for most non-disclosing operations.

To create a Hook URL:

  1. Access your API Fortress dashboard.
  2. Enter the company configuration screen (gear icon in the top right corner).
  3. Choose API Hooks in the sidebar.
  4. Create a new Hook by choosing the user (necessary for advanced functions) and the project.
  5. A unique URL will be generated. That is the URL to be used in your build step configuration.

Test IDs and Project ID

To retrieve a specific test ID from the API Fortress dashboard:

  1. Access the tests list for the project you intend to use.
  2. Edit one of tests and access the interstitial page.
  3. Click on “show/hide test information.”APIHookLink
  4. The test ID and the Project ID are shown here.

jenkins4