frock

frock

A plugin-based tool for running fake HTTP and socket services.

frock is a tool for running fake services and serving mock data. It's designed for developers who work in service-oriented architectures, and need to stand up fake services that approximate production services in their development environments.

frock itself is a host for running HTTP and socket services, and its HTTP router makes it simple to run multiple services on the same port. Outside of the core functions of starting services and routing to handlers, frock's functionality is implemented through plugins and middleware that you write.

There are some generic plugins provided for out-of-the-box functionality:

• frock-static is a plugin for serving static content from files, directories, or URLs.
• frock-proxy is a plugin for proxying requests from frock to a remote server.

For a quick overview of the functionality frock provides, see the example in this README.

Quick-Start Example

frock is a Node.js CLI utility, which loads a frockfile from your project directory. In the following example, we'll create a service that proxies requests to your local development server at http://localhost:8052, but intercepts some URLs to serve static content from a variety of sources.

In your working directory, create a frockfile.json:

{
  "servers": [
    {
      "port": 8080,
      "routes": [
        {
          "path": "/api/segments",
          "methods": ["GET"],
          "handler": "frock-static",
          "options": {
            "file": "fixtures/static/segments.json",
            "contentType": "application/json"
          }
        },
        {
          "path": "/api/remote",
          "methods": ["GET"],
          "handler": "frock-static",
          "options": {
            "url": "http://raw.githubusercontent.com/somewhere/something.json",
            "contentType": "application/json"
          }
        },
        {
          "path": "*",
          "methods": "any",
          "handler": "frock-proxy",
          "options": {
            "url": "http://localhost:8052"
          }
        }
      ]
    }
  ]
}

Install frock and the plugins you requested:

$ npm install frock frock-static frock-proxy

Then, run frock:

$ frock

This examples expects that your PATH is set to run Node.js packages from your project's installed node_modules; see the Understanding Packages section of the documentation for details.

Note: By default, frock only allows connections from localhost; see the docs on connection filtering for details.

Detailed Documentation

frock's documentation is split into several sections:

• Using frock in your project/Understanding Packages is an overview of how frock is meant to sit alongside your project.
• Implementing mocks/fakes:
  • Plugins: writing plugins, where you'll implement your fake services.
  • Middleware: writing middleware, which can augment your plugins' functionality.
  • Cores: writing cores, which can extend the core functionality of frock.
• frockfile Reference, which explains the configuration file format that frock uses, the frockfile.json
• Examples which provides detailed examples of using frock, and can help you understand how to implement your fake services.
• API details the frock API, which can be used programatically rather than via the provided CLI. This also documents the frock singleton your plugins will be passed when they are instantiated.

CLI

The frock command will search upward from your current directory for a frockfile.json, and run it; it will also start up a watcher on that file and hot-reload on any changes made to it.

Use the built-in help to learn about other options:

$ frock --help

Some options can be set via environment variables; these provide defaults, which can still be overridden by explicitly passing CLI flags. Set these to any value besides an empty string to set the default to true:

• FROCK_NO_WATCH disable watching the frockfile to reload changes
• FROCK_DEBUG set the log level to debug
• FROCK_RAW_OUTPUT output the raw log JSON rather than pretty-printing
• FROCK_UNSAFE_DISABLE_CONNECTION_FILTERING disable processing of whitelists/blacklists for connections, and allow any incoming connections

Testing

From the project directory:

$ npm test

Any test file that should be run must be required in the tests/index.js file.

License

Apache 2.0, see LICENSE for details.

Changelog

[2.0.0]

• Adds integration test to catch errors, such as those fixed in [1.1.1]
• Removes tests for unsupported versions of Node.js
• Specifies supported engines in package.json
• Fixes a bug that would crash frock when using socket servers on versions of Node.js greater than v4.