Drosse The ultimate mock server

Tight to your project

Because drosse is a node package, your mocks and your mock-server are part of your project. You can run as many drosse instances as you want.

Of course, you can also install it globally or even use the docker version if you wish.

Easy configuration

Configuring drosse is as simple as writing its port number in a .drosserc.js file and writing route definitions in a routes.json file.

.drosserc.js contains advanced configurations as well.

Cascading configs

Routes are defined as a JSON tree of sub-paths. Handlers (GET, POST, etc.) and plugins (throttle, proxy, etc.) are configured via the DROSSE key in your route object.

All plugin configs are inherited by child routes unless they overwrite it.

//routes.json
{
  "api": {
    "users": {
      "DROSSE": {
        "throttle": { // activate throttle plugin
          "min": 100,
          "max": 1000
        }
      },
      "jorinho": { // inherits throttle from `users`
        "detail": {
          "DROSSE": {
            "throttle": { // overwriten!
              "min": 2000,
              "max": 2500
            ...

Static mocks

Drosse handles mocks written directly in the routes.json file (inline mode) or in JSON files (static mode).

Inline mocks are very useful for quick setup but you'll probably use static mode for most use cases. When doing so, your file name should match its route path.

//routes.json
{
  "api": {
    "users": {
      "DROSSE": {
        "get": {
          "body": [{ // inline mocks
            "id": 1,
            "name": "Tadai"
          }]
        }
      },
      "jorinho": {
        "get": {
          "static": true // static (in-file) mocks
                         // => ./static/api.users.jorinho.get.json
        ...

Dynamic mocks

You can use javascript to build responses dynamically, which gives you access to the persisted data api as well as the express request object and the NodeJs environment 🦄 .

Simply set "service":true in your route definition and create a javascript file matching the route path.

Assets handling

Drosse can serve static files that are not JSON via the "assets":true setting. This is handy if you need to mock multimedia content.

By using a file path as value instead of true, you can even have a basic URL rewrite mechanism.

Dynamic URL params

Dynamic parameters in routes is a common use case in REST APIs. You can define those with a colon (e.g. /api/users/:id) in the routes.json file.

If you want a single file to match any value of the dynamic param, you can create such one with the param enclosed in curly brackets ({param}) in its file name.

You can also use the curly brackets syntax inside your JSON, it will be replaced by drosse with the value in the request.

// routes.json
{
  ":id": {
    "DROSSE": {
      "get": {
        "body": {
          "id": "{id}",
          "name": "User {id}"
        }
      ...

Data persistence

Drosse provides an in-memory JSON database in service mode, enabling stateful interactive mocking.

The database is fed at startup with JSON files, organised in collections. It dumps its state to disk every 4s in a single JSON file. Deleting this file gives you a fresh state.

You can even tell Drosse to reload some collections at each start while keeping others stateful.

Drosse's db API makes it very easy to perform read and write operations.

Throttling

You can delay the response time of your routes via the throttle setting, giving a minimum and a maximum delay time. All child routes inherit from it by default.

To prevent inheritance, simply throttle the direct child routes to 0.

Great for testing frontend async handling 😉.

Proxying

Routes can be proxied to other services via the proxy setting, which is applied to child routes as well unless otherwise specified.

You can even fallback to another local mock server by setting a proxy on the topmost level of your routes 😜

// Drosse running on localhost:8000
{
  "DROSSE": {
    "proxy": "http://localhost:7000"
  },
  "api": {
    "users": {
  ...

Middlewares

You can extend Drosse with custom express middlewares to fulfill your use cases.

Some basic ones are built-in (CORS, logging, etc.) and we provide a useful example of a session middleware in case you need to mock user login in your app.

Templates

Templates are javascript functions that take JSON as input and return a transformed version of it. Unlike plugins, they are applied at the end of the processing chain.

Templates help you structure and organize your mocks the way you want and format the response the way you need.

Extensible REPL CLI

Last but not least, Drosse is interactive once it has started and created all your routes. You can type built-commands and create custom ones as well.

Think of an inbox module where support/helpdesk team can interact with users via inbox or message. You could mock that behavior with custom commands.

Desktop UI app coming soon

Oh and we are very close to ship a desktop application where you can control and manage all your drosse instances without opening the terminal.

Stay tuned 📣