Getting started

Your first PASS

One GET, one check, PASS. That’s the whole loop. Auth and extra tests can wait.

Playground

Open the playground. This sample should already be loaded:

SUITE: Hello API
URL: mock://api

TEST: Get Users
  GET: /users
  EXPECT: status == 200

mock://api isn’t the internet — the tab answers GET /users itself. Click Run. You want something like:

SnapAPI  Hello API
Using in-memory mock API  (GET /users or /api/users, /health, /jobs/:id)

  Get Users
    GET /users                        200  1ms
    PASS  0ms

  1 passed  0 failed  1ms

Millisecond numbers bounce around. The 1 passed is what matters.

Install the CLI

Package on PyPI is pysnapapi. The command is snapapi. Don’t pip install snapapi — that’s someone else’s project (SNAP payments).

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install pysnapapi
snapapi --version

You want snapapi 0.3.0 or newer. command not found means the venv isn’t active in this terminal. externally-managed-environment means you skipped the venv. More on Install.

Same GET on your machine

The playground fakes HTTP in the tab. The CLI sends a real request, so something has to listen. snapapi mock is a tiny server for that.

Drop these two files in an empty folder. You don’t need to clone the repo. First, mock.json:

{
  "routes": [
    {
      "method": "GET",
      "path": "/users",
      "status": 200,
      "json": { "data": [{ "id": 1, "name": "Ada" }] }
    }
  ]
}

Then hello.sapi. Same GET, but URL: is the mock:

SUITE: Hello API
URL: http://127.0.0.1:8765

TEST: Get Users
  GET: /users
  EXPECT: status == 200

Leave this running in one terminal (it prints the URL):

snapapi mock mock.json --port 8765

In another terminal, same folder, venv active:

snapapi hello.sapi

If you cloned the repo, these files are already at examples/hello/mock.json and examples/hello/hello.sapi.

A good run looks like:

SnapAPI  Hello API

  Get Users
    GET /users                        200  1ms
  PASS  1ms

  1 passed  0 failed  1ms

GET /users hit port 8765, the mock returned 200, that matched the EXPECT, so it PASSed.

If it failed

You see	What it means	What to do
`command not found`	The venv is not active in this terminal.	`source .venv/bin/activate` (Windows: `.venv\Scripts\activate`).
`Connection refused` / `ERR`	Nothing is listening on that port. The mock is not running.	Start `snapapi mock` first. Keep it in the other terminal.
HTML 404 from `SimpleHTTP`	Port 8765 is some other Python server, not the SnapAPI mock.	Stop it, or use `--port 9876` and change `URL:` to `http://127.0.0.1:9876`.
`Status code expected 200, got 404`	HTTP reached a server, but `/users` is not a route there.	You are not hitting `mock.json`. Check the port and that the mock is the SnapAPI one.
`Status code expected 201, got 200`	The request worked. Your EXPECT does not match the response.	That is a failed test, not a broken install. Fix the EXPECT or the mock.
`No such file or directory`	Wrong path or wrong folder.	Run `snapapi hello.sapi` from the folder that contains the file. Exit code `2`.
`Unknown keyword`	A typo in the `.sapi` file (keywords are one token, no spaces).	Fix the line. Exit code `2`.
`Undefined variable ${…}`	This hello file has no `${}`. You opened a different suite.	Use the five-line file on this page. More cases: Troubleshooting.

New terminal tabs don’t inherit the venv. Activate it in both. Longer list: Troubleshooting.

Check the body too

The mock returns {"data": [{"id": 1, "name": "Ada"}]}. You can assert on that without adding a second request:

TEST: Get Users
  GET: /users
  EXPECT: status == 200
  EXPECT: body contains data

Run it again. Still 1 passed — two checks on the same response.

That’s a working test. When you want more:

When SnapAPI is not for you · Plugins · Troubleshooting if something’s off. Full keyword list: DSL reference.

PreviousInstall NextPOST