Mocko CLI

Mocko CLI is a Mocko module that allows you to run it in your terminal. Mocko is an HTTP Mocking utility that lets you create dynamic mocks and proxy your API when no mocks are defined.

Installation

:warning: You need NodeJS 14 or newer installed

First install the Mocko CLI with npm, you might need sudo for Linux or Mac:

npm i -g @mocko/cli

Check the installation with the --help flag for the help screen:

$ mocko --help
Usage: mocko [options] <path to mocks folder>
Example: mocko -p 4000 mocks

Options:                    

  -h, --help       Shows this screen
  -v, --version    Shows the current version
  -w, --watch      Watches for file changes and restarts the server
  -p, --port       Port to serve the mocks (8080)
  -u, --url        URL to proxy requests when no mock is defined
  -t, --timeout    Max time to wait for a response from the proxied URL in millis (30000)

Creating your first project

Now that you have Mocko CLI installed, let's create your first Mocko project, create a folder with a .hcl file inside, a simple structure like this:

hello-mocko
└── first-mocks.hcl

And, in your .hcl file (like our first-mocks.hcl), create your first mock with the mock stanza:

mock "GET /hello" {
  body = "Hello from Mocko!"
}

:information_source: Your IDE or editor will most likely have an extension for .hcl syntax highlighting. It might help :)

Using Mocko

Now that you have Mocko CLI installed and your first project created, we're ready to begin. Inside your project folder, start Mocko by running the command:

mocko --watch .

And, as easy as that, your mocks are now being served on port 8080. If you want to change the port, you can use the --port flag to choose another one. Also, the --watch flag we've used makes Mocko auto reload the changes you save to your mock definitions. The . (dot) in the command is the folder that contains your mocks (or folder with folders of them), as we're inside it, we used . but you could pass any path.

To see your mock being served you can use any HTTP client like Insomnia, HTTPie, cURL or, in this case as its a GET request, even your browser. Simply access http://localhost:8080/hello in your browser or, with curl:

$ curl http://localhost:8080/hello
Hello from Mocko!

The mock stanza

The mocks are defined using HCL, you can check it's documentation here.

Our first mock was super easy to create but is too simple, let's zhuzh is up a bit =P

You can have multiple mocks in a file so let's add a comment to our first one, just to identify it, and create a new mock:

# Our first, simple, hello mock
mock "GET /hello" {
  body = "Hello from Mocko!"
}

# Mocking George, the cat
mock "GET /cats/george" {
  # This is how you set response status, it's optional and defaults to 201 for POST and 200 for other methods
  status = 200

  # Headers are defined in a map, don't forget your content type
  headers {
    Content-Type = "application/json"
  }

  # You can use multi-line strings for your body
  body = <<EOF
  {
    "id": 1,
    "name": "George"
  }
  EOF
}

And now let's understand it a little better:

Method and path

You define the method and path right after the mock stanza. They're interpreted by Hapi Call, you can check its documentation here.

You can choose any method or * to match all. For the path, you can use specific paths like /cats/george or generic ones like /cats/{name}. You can even use optional parameters (/cats/{name?}), multi-segment parameters (/cats/{name*2}) or even catch-all parameters (/cats/{name*}).

Specific paths will always be matched with higher priority, if you had two mocks:

mock "GET /cats/george" { status = 204 }
mock "GET /cats/{name}" { status = 404 }

A get to /cats/george would never trigger the last mock (generic) regardless of the order, only the first one (specific). Other calls like /cats/alice would trigger the latter.

status parameter

Not much to say here... You can choose any status from 200 to 599. It defaults to 201 for POST mocks or 200 for anything else.

headers parameter

Here you can specify your headers in a map like so:

headers {
  Content-Type    = "application/json"
  X-Custom-Header = "Mocko is amazing :O"
}

Don't forget your Content-Type header =P

delay parameter

While we didn't use it yet, you could specify a delay parameter to add a delay to your response, you can choose any number in milliseconds.

body parameter

All of Mocko's magic is in this parameter... But we won't go deep here yet :X

There is an entire section about templating that you can learn more about this. Don't worry, we'll remind you in the end of this page.

Structuring your mocks

Your mocks don't need to be in the root of your folder, they can be inside folders in any deepness. Also, you can define multiple mocks in the same file. Here's a folder structure example:

.
├── user
│   ├── homepage.hcl
│   └── profile.hcl
└── wallet
    ├── credit
    │   ├── credit.hcl
    │   └── indication.hcl
    ├── payment
    │   ├── creditcard.hcl
    │   └── gateway.hcl
    └── refund.hcl

Next steps

Before moving on, how about leaving us a star on GitHub? It'll take you two clicks, first here and then on star :)

Now that you learned to use Mocko CLI, learned to create your mocks using HCL, structure them in a project and even gave us an star on GitHub (right?) it's time to learn the main functionality of Mocko: templating. With it, you can create dynamic mocks, write logic for them so that you can simulate the more complicated scenarios. See you there :)