Run API tests in CI

Cloak Proxy’s API client is a collection of plain JSON files, so your requests and their tests live in Git and run in CI with no app, like Newman or the Postman CLI. This guide writes tests on a request, commits the workspace, and runs the collection in GitHub Actions, exporting JUnit XML for the test report.

What you need

The API client with a collection and an environment	See Collections and requests
cloakctl available in CI	It ships inside the app bundle at Contents/Resources/cloakctl; CI usually runs it from a checked-out copy or a linked path
A Git repository for the workspace	The runner reads the folder of JSON files directly

Write tests on a request

1. In the API Client (<kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>O</kbd>), open a request and go to its Scripts tab, then Post-response. Write assertions with pm.test and pm.expect.

   1234

   Post-response tests on a request, with results below.

   1. Scripts tab
   2. Post-response phase
   3. pm.test / pm.expect assertions
   4. Test Results after Send

   ×

   

2. Use the Snippets menu for common checks (status is 2xx, response time, JSON value, schema). Press Send to run them; results appear under Test Results.

Post-response script

pm.test("Status code is 2xx", () => pm.response.to.be.success);
pm.test("Responds within 500 ms", () => pm.expect(pm.response.responseTime).to.be.below(500));
const json = pm.response.json();
pm.test("Has a name", () => pm.expect(json).to.have.property("name"));

Tip

Keep secrets out of the repo. Store API keys in the Vault and reference them as {{vault:name}}, or mark an environment variable as a secret so its value stays in the git-ignored .cloak/ folder.

Check the run locally

Open Collections, select the collection, and click Run to open the runner. Set iterations, pick a dataset or data file for data-driven runs, and run it.

1234

The collection runner. The same run happens headlessly in CI.

1. Iterations and options
2. A dataset or CSV/JSON data file
3. Passed / failed summary
4. Export Results: JSON, JUnit XML, HTML

×

Commit the workspace to Git

The workspace is a folder of small, pretty-printed JSON files — one per request — so it diffs and merges cleanly. Secret values stay in a git-ignored .cloak/ folder.

• cloak-workspace.json
• Directorycollections/

  • DirectoryPetstore/

    • collection.json
    • List pets.request.json
    • Create pet.request.json
• Directoryenvironments/

  • Staging.environment.json
• Directoryspecs/

  • …
• Directory.cloak/ (git-ignored: secret values, local state)

  • …
• .gitignore

1. Open the Git view in the API client to see the workspace folder. Use Change Folder… to point the workspace at your repo, or Initialize Repository to start one.

   1234

   The Git view: the workspace folder, ready to commit.

   1. Git section
   2. Workspace folder path
   3. Change Folder to point at your repo
   4. Initialize Repository

   ×

   

2. Commit from the Git view (enter a message and Commit All), or from your terminal. Confirm .cloak/ is ignored before you push.

Run it in GitHub Actions

cloakctl collection run runs the collection with its scripts and tests and returns a non-zero exit code when any test or request fails. Export JUnit XML for the test report.

Terminal

cloakctl collection run Petstore -e Staging -r cli,junit --reporter-junit-export results.xml

.github/workflows/api-tests.yml

name: API tests
on: [push, pull_request]
jobs:
  test:
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v4
      - name: Run collection
        run: |
          cloakctl collection run Petstore \
            -e Staging \
            -r cli,junit \
            --reporter-junit-export results.xml
      - name: Publish test report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-results
          path: results.xml

Note

Run cloakctl from the path where it lives in your setup — for example the app bundle’s Contents/Resources/cloakctl, or a symlink you created (Settings → Advanced → Link to /usr/local/bin). The workflow above assumes it’s on PATH.

The flags you’ll use

Flag	What it does
-e ENV	Run with an environment (name or a .json file)
-d DATA	A dataset name or CSV/JSON data file: one iteration per row
-n N	Iteration count
--folder NAME	Run only one folder
--bail	Stop after the first failure
--timeout-request MS	Per-request timeout
--insecure	Skip TLS verification (same as -k)
-r cli,json,junit,html	Which reporters to produce
--reporter-junit-export FILE	Where to write the JUnit XML
--reporter-json-export FILE	Where to write the JSON report
--reporter-html-export FILE	Where to write the HTML report
--env-var KEY=VALUE	Override or add an environment variable
--workspace DIR	Use a specific workspace folder

Exit code is 1 when any test or request fails, which fails the CI step.

Tip

cloakctl collection list prints the collections and environments in the workspace, so you can confirm the names your workflow passes to run.

Related

Scripts and testsThe pm.* API, assertions and packages.

Collection runnerIterations, order, folders and delays.

Workspace and GitThe folder format, the .cloak/ secrets, and the Git view.

cloakctlEvery command and flag.