[opensourcedex]

smocker is a free, open source api development & testing project written in TypeScript and released under MIT. It has 1,284 GitHub stars, 71 forks and 14 open issues, and was last pushed 4 days ago. On this registry it ranks #85 of 103 tracked projects in API Development & Testing, with 5 head-to-head comparisons available.

What is smocker?

What it is

Smocker is an open-source HTTP mock server and proxy for API development and testing. It lives in the developer-tools ecosystem, where teams simulate third-party services, stub routes, and inspect interactions without building a full backend. The project is MIT licensed, written in TypeScript, and distributed as a Docker image or manual deployment archive.

The problem it solves is the need for a lightweight local service that answers configured HTTP requests and can also proxy other services. Instead of editing application code or deploying temporary stub servers, a developer registers mock routes through a configuration API and points the system under test at Smocker. The README shows a two-port model: port 8080 serves mocks, and port 8081 exposes configuration and a browser UI.

Key capabilities

  • It serves configured HTTP responses for registered routes, including status codes, headers, and JSON bodies.
  • It can act as an HTTP mock server and proxy for API testing workflows.
  • It accepts mock definitions in YAML and JSON, with a JSON Schema at docs/mock.schema.json for editor validation.
  • It exposes a configuration API for creating mocks and resetting the mock server without restarting the process.
  • It includes a web UI for viewing history and managing mocks through a browser.
  • It can be deployed with Docker using ghcr.io/smocker-dev/smocker or manually with a release archive and command-line flags.

Who uses it and how

  • Backend and frontend developers run it locally during integration tests when a dependent HTTP service is unavailable or slow.
  • QA engineers register YAML or JSON mocks, run tests against port 8080, and inspect history in the UI on port 8081.
  • Teams can containerize it with Docker for ephemeral test environments.
  • Teams use the reset endpoint to clear mocks between scenarios instead of restarting the container or binary.

Getting started

The typical install methods are Docker with ghcr.io/smocker-dev/smocker, or manual deployment with a release archive and flags for the mock and configuration ports. A health check is available at localhost:8081/version, and the user interface is available at http://localhost:8081/.

When to use it — and when not to

Smocker is useful when a team wants a small self-hosted mock server with a simple configuration API and browser UI for local or containerized testing. It may be less suitable when a project needs a fully managed hosted mock service, because the provided facts describe self-hosting through Docker or a manual binary. Operators must manage deployment, port bindings, mock registration, and reset behavior themselves, and the README excerpt does not mention built-in database, storage, SMTP, or authentication requirements.

project readme (upstream, from github) — read inline

CI Docker Repository Github Release License

Smocker (server mock) is a simple and efficient HTTP mock server.

The documentation is available on smocker.dev.

Table of contents

Installation

With Docker

docker run -d \
  --restart=always \
  -p 8080:8080 \
  -p 8081:8081 \
  --name smocker \
  ghcr.io/smocker-dev/smocker

Manual Deployment

# This will be the deployment folder for the Smocker instance
mkdir -p /opt/smocker && cd /opt/smocker
wget -P /tmp https://github.com/smocker-dev/smocker/releases/latest/download/smocker.tar.gz
tar xf /tmp/smocker.tar.gz
nohup ./smocker -mock-server-listen-port=8080 -config-listen-port=8081 &

Healthcheck

curl localhost:8081/version

User Interface

Smocker exposes a configuration user interface. You can access it in your web browser on http://localhost:8081/.

History

Mocks

Usage

Smocker exposes two ports:

  • 8080 is the mock server port. It will expose the routes you register through the configuration port
  • 8081 is the configuration port. It's the port you will use to register new mocks. This port also exposes a user interface.

Hello, World!

To register a mock, you can use the YAML and the JSON formats. A basic mock might look like this:

# helloworld.yml
# This mock register two routes: GET /hello/world and GET /foo/bar
- request:
    # Note: the method could be omitted because GET is the default
    method: GET
    path: /hello/world
  response:
    # Note: the status could be omitted because 200 is the default
    status: 200
    headers:
      Content-Type: application/json
    body: >
      {
        "hello": "Hello, World!"
      }

- request:
    method: GET
    path: /foo/bar
  response:
    status: 204

You can then register it to the configuration server with the following command:

curl -XPOST \
  --header "Content-Type: application/x-yaml" \
  --data-binary "@helloworld.yml" \
  localhost:8081/mocks

After your mock is registered, you can query the mock server on the specified route, so that it returns the expected response to you:

$ curl -i localhost:8080/hello/world
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 05 Sep 2019 15:49:32 GMT
Content-Length: 31

{
  "hello": "Hello, World!"
}

To cleanup the mock server without restarting it, you can execute the following command:

curl -XPOST localhost:8081/reset

For more advanced usage, please read the project's documentation.

Mock format schema

A JSON Schema describing the mock format lives at docs/mock.schema.json. It is generated from and kept in sync with the Go types (server/types): the example mocks under tests/data are validated against it in CI, so it stays accurate. The documentation references this file as the canonical schema.

Editors can use it for autocompletion and validation. With the YAML language server (VS Code, Neovim, …), add this line at the top of a mocks file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/smocker-dev/smocker/main/docs/mock.schema.json
- request:
    path: /hello
  response:
    body: '{"message": "Hello, World!"}'

Development

Backend

The backend is written in Go. You can use the following commands to manage the development lifecycle:

  • make start: start the backend in development mode, with live reload
  • make build, make VERSION=xxx build: compile the code and generate a binary
  • make lint: run static analysis on the code
  • make format: automatically format the backend code
  • make test: execute unit tests
  • make test-integration: execute integration tests

Frontend

The frontend is written with TypeScript and React, bundled with Vite. You can use the following commands to manage the development lifecycle:

  • npm install: install the dependencies
  • npm run dev: start the Vite dev server with hot reload. It proxies the admin API to the backend, so run make start alongside it (override the target with SMOCKER_DEV_PROXY if the backend is elsewhere)
  • npm run build: generate the transpiled and minified files and assets
  • npm run lint: run static analysis on the code
  • npm run format: automatically format the frontend code
  • npm test: execute unit tests
  • npm run test:watch: execute unit tests, with live reload

Docker

The application can be packaged as a standalone Docker image. You can use the following commands to manage the development lifecycle:

  • make build-docker, make VERSION=xxx build-docker: build the application as a Docker image
  • make start-docker, make VERSION=xxx start-docker: run a Smocker Docker image

Caddy

If you need to test Smocker with a base path, you can use the Caddyfile provided in the repository (Caddy v2):

  • make start-release, make VERSION=xxx start-release: create a released version of Smocker and launch it with /smocker/ as base path
  • make start-caddy: start Caddy to make Smocker accessible at http://localhost:8082/smocker/

HTTPS

If you need to test Smocker with HTTPS enabled, the easiest way is to generate a locally signed certificate with mkcert:

# Install the local certificate authority
mkcert -install

# Create a certificate for localhost
mkcert -cert-file /tmp/cert.pem -key-file /tmp/key.pem localhost

Then, start Smocker with TLS enabled, using your generated certificate:

./smocker -mock-server-listen-port=44300 -config-listen-port=44301 -tls-enable -tls-cert-file=/tmp/cert.pem -tls-private-key-file=/tmp/key.pem

Authors

Contributors

Frequently asked questions

Is smocker free to use?

smocker is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does smocker do?

Smocker is a simple and efficient HTTP mock server and proxy

What is smocker written in?

smocker is primarily written in TypeScript. Its source is publicly available at https://github.com/smocker-dev/smocker, and it has 1,284 GitHub stars.