{"id":13434127,"url":"https://github.com/namshi/mockserver","last_synced_at":"2025-05-15T23:04:00.273Z","repository":{"id":17851434,"uuid":"20771539","full_name":"namshi/mockserver","owner":"namshi","description":"Mock your backends in a matter of seconds. HTTP is King.","archived":false,"fork":false,"pushed_at":"2024-05-28T19:26:51.000Z","size":273,"stargazers_count":350,"open_issues_count":43,"forks_count":89,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-08T10:15:55.962Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/namshi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-06-12T14:58:58.000Z","updated_at":"2025-03-28T18:46:20.000Z","dependencies_parsed_at":"2024-06-18T12:41:42.339Z","dependency_job_id":"26e13274-a2fa-412b-89ee-f5ca6d9aa9e9","html_url":"https://github.com/namshi/mockserver","commit_stats":{"total_commits":124,"total_committers":28,"mean_commits":4.428571428571429,"dds":0.6129032258064516,"last_synced_commit":"39b3e8df58659214a2ecd48aa1d07983bdbdb2c4"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fmockserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fmockserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fmockserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namshi%2Fmockserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/namshi","download_url":"https://codeload.github.com/namshi/mockserver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436944,"owners_count":22070946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T02:01:47.059Z","updated_at":"2025-05-15T23:04:00.253Z","avatar_url":"https://github.com/namshi.png","language":"JavaScript","readme":"# Deprecation notice\n\nThis project is not under active maintenance (see https://github.com/namshi/mockserver/issues/82)\n\nDevelopment is continued at https://github.com/fauxauldrich/camouflage\n\nFor details on how to port your existing projects please visit [Camouflage Documentation](https://fauxauldrich.github.io/camouflage), or post your questions in Camouflage's [discussion](https://github.com/fauxauldrich/camouflage/discussions/22)\n\n# mockserver\n\n[![Build Status](https://travis-ci.org/namshi/mockserver.svg?branch=master)](https://travis-ci.org/namshi/mockserver)\n\n**mockserver** is a library that will help you mocking your APIs\nin **a matter of seconds**: you simply organize your mocked\nHTTP responses in a bunch of mock files and it will serve them\nlike they were coming from a real API; in this way you can\nwrite your frontends without caring too much whether your\nbackend is really ready or not.\n\n## Installation\n\nMockserver can be installed globally if you need\nto run it as a command:\n\n```\n$ npm install -g mockserver\n\n$ mockserver -p 8080 -m test/mocks\nMockserver serving mocks under \"test/mocks\" at http://localhost:8080\n```\n\nor as a regular NPM module if you need to use it as\na library within your code:\n\n```bash\nnpm install mockserver\n```\n\nthen in your test file:\n\n```javascript\nvar http = require('http');\nvar mockserver = require('mockserver');\n\nhttp.createServer(mockserver('path/to/your/mocks')).listen(9001);\n```\n\nThis will run a simple HTTP webserver, handled by mockserver, on port 9001.\n\nAt this point you can simply define your first mock: create a file in\n`path/to/your/mocks/example-response` called `GET.mock`:\n\n```\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=utf-8\n\n{\n   \"Random\": \"content\"\n}\n```\n\nIf you open your browser at `http://localhost:9001/example-response`\nyou will see something like this:\n\n![example output](https://raw.githubusercontent.com/namshi/mockserver/readme/bin/images/example-response.png)\n\nAnd it's over: now you can start writing your frontends without\nhaving to wait for your APIs to be ready, or without having to spend\ntoo much time mocking them, as mockserver lets you do it in seconds.\n\n## Verbosity\n\nBy default mockserver is running in verbose mode: log messages are pushed to `stdout`.\nThat will help to distinguish, which mock file matches best the request.\n\n```shell\n$ mockserver -p 8080 -m './mocks'\nMockserver serving mocks {verbose:true} under \"./mocks\" at http://localhost:8080\nReading from ./mocks/api/GET--a=b.mock file: Not matched\nReading from ./mocks/api/GET.mock file: Matched\n```\n\nOption `-q|--quiet` disables this behavior.\n\n## Mock files\n\nAs you probably understood, mock files' naming conventions are based\non the response that they are going to serve:\n\n```\n$REQUEST-PATH/$HTTP-METHOD.mock\n```\n\nFor example, let's say that you wanna mock the response of a POST request\nto `/users`, you would simply need to create a file named `POST.mock` under `users/`.\n\nThe content of the mock files needs to be a valid HTTP response, for example:\n\n```\nHTTP/1.1 200 OK\nContent-Type: text/xml; charset=utf-8\n\n{\n   \"Accept-Language\": \"en-US,en;q=0.8\",\n   \"Host\": \"headers.jsontest.com\",\n   \"Accept-Charset\": \"ISO-8859-1,utf-8;q=0.7,*;q=0.3\",\n   \"Accept\": \"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\"\n}\n```\n\nCheck [our own mocks](https://github.com/namshi/mockserver/tree/master/test/mocks) as a reference.\n\n## Custom Headers\n\nYou can specify request headers to include, which allows you to change the response based on what headers are\nprovided.\n\nTo do this, you need to let mockserver know which headers matter,\nby exposing comma-separated environment `MOCK_HEADERS` variable, like so:\n\n```shell\n$ MOCK_HEADERS=x-foo,authorization mockserver -m . -p 9001\n```\n\nOr by setting the `headers` array on the mockserver object, like so:\n\n```js\nvar mockserver = require('mockserver');\nmockserver.headers = ['Authorization', 'X-My-Header'];\n```\n\nAny headers that are set and occur within the array will now be appended to the filename, immediately after the\nHTTP method, like so:\n\n```\nGET /hello\nAuthorization: 12345\n\nhello/GET_Authorization=12345.mock\n```\n\n```\nGET /hello\nX-My-Header: cow\nAuthorization: 12345\n\nhello/GET_Authorization=12345_X-My-Header=cow.mock\n```\n\n**Note:** The order of the headers within the `headers` array determines the order of the values within the filename.\n\nThe server will always attempt to match the file with the most tracked headers, then it will try permutations of\nheaders until it finds one that matches. This means that, in the previous example, the server will look for files\nin this order:\n\n```\nhello/GET_Authorization=12345_X-My-Header=cow.mock\nhello/GET_X-My-Header_Authorization=12345=cow.mock\nhello/GET_Authorization=12345.mock\nhello/GET_X-My-Header=cow.mock\nhello/GET.mock\n```\n\nThe first one matched is the one returned, favoring more matches and headers earlier in the array.\n\nThe `headers` array can be set or modified at any time.\n\n## Response Delays\n\nWhen building applications, we cannot always guarantee that our users have a fast connection, which\nis latency free. Also some HTTP calls inevitably take more time than we'd, like so we have added\nthe ability to simulate HTTP call latency by setting a custom header\n\n```\nResponse-Delay: 5000\n```\n\nThe delay value is expected in milliseconds, if not set for a given file there will be no delay.\n\n## Query string parameters and POST body\n\nIn order to support query string parameters in the mocked files, replace all occurrences of `?` with `--`, then\nappend the entire string to the end of the file.\n\n```\nGET /hello?a=b\n\nhello/GET--a=b.mock\n```\n\n```\nGET /test?a=b\u0026c=d?\n\ntest/GET--a=b\u0026c=d--.mock\n```\n\n(This has been introduced to overcome issues in file naming on windows)\n\nTo combine custom headers and query parameters, simply add the headers _then_ add the parameters:\n\n```\nGET /hello?a=b\nAuthorization: 12345\n\nhello/GET_Authorization=12345--a=b.mock\n```\n\nSimilarly, you can do the same thing with the body of a POST request:\nif you send `Hello=World` as body of the request, mockserver will\nlook for a file called `POST--Hello=World.mock`\n\nIn the same way, if your POST body is a json like `{\"json\": \"yesPlease\"}`,\nmockserver will look for a file called `POST--{\"json\": \"yesPlease\"}.mock`.\n_Warning! This feature is_ **NOT compatible with Windows**_. This is because Windows doesn't accept curly brackets as filenames._\n\nIf no parametrized mock file is found, mockserver will default to the\nnearest headers based .mock file\n\nex:\n\n```\nGET /hello?a=b\nAuthorization: 12345\n```\n\nif there's no `hello/GET_Authorization=12345--a=b.mock`, we'll default to `hello/GET_Authorization=12345.mock` or to `hello/GET.mock`\n\n## Wildcard slugs\n\nIf you want to match against a route with a wildcard - say in the case of an ID or other parameter in the URL, you can\ncreate a directory named `__` as a wildcard.\n\nFor example, let's say that you want mock the response of a GET request\nto `/users/:id`, you can create files named `users/1/GET.mock`, `users/2/GET.mock`, `users/3/GET.mock`, etc.\n\nThen to create one catchall, you can create another file `users/__/GET.mock`. This file will act as a fallback\nfor any other requests:\n\nex:\n\n```\nGET /users/2\n\nGET /users/2/GET.mock\n```\n\nex:\n\n```\nGET /users/1000\n\nGET /users/__/GET.mock\n```\n\nex:\n\n```\nGET /users/1000/detail\n\nGET /users/__/detail/GET.mock\n```\n\n## Custom imports\n\nSay you have some json you want to use in your unit tests, and also serve as the body of the call. You can use this import syntax:\n\n```\nHTTP/1.1 200 OK\nContent-Type: application/json\n\n#import './data.json';\n```\n\nwhereby `./data.json` is a file relative to the including mock file. You can have as many imports as you want per mock file.\n\nYou can also import `javascript` modules to create dynamic responses:\n\n```js\n// script.js\nmodule.exports = {\n  id: Math.random()\n    .toString(36)\n    .substring(7),\n  date: new Date(),\n};\n```\n\nThen import the file as above `#import './script.js'`\n\nDynamic values of headers can be filled with valid JS statements such as:\n\n```\nX-Subject-Token: #header ${require('uuid/v4')()};\n```\n\n## Custom response status\n\nYou can specify response status (200, 201, 404. etc.) depending on request parameters. To do this, you need to use `#import './code.js';` in first line of your mock file:\n\n```\n#import './code.js';\nContent-Type: application/json; charset=utf-8\nAccess-Control-Allow-Origin: *\n\n{\n \"Random\": \"Content\" \n}\n```\n\nYou import `javascript` modules to create dynamic code responses:\n\n```js\n// code.js\nmodule.exports = request.body.indexOf('foo') !== -1 ? 'HTTP/1.1 200 OK' : 'HTTP/1.1 400 Bad request'\n```\n\n## Tests\n\nTests run on travis, but if you wanna run them locally you simply\nhave to run `mocha` or its verbose cousin `./node_modules/mocha/bin/mocha`\n(if you don't have mocha installed globally).\n\nTo run test with debug output, expose `DEBUG=true` environment variable:\n\n```shell\n$ DEBUG=true ./node_modules/mocha/bin/mocha\n```\n\nOr as npm shortcut:\n\n```shell\n$ DEBUG=true npm test\n```\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamshi%2Fmockserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnamshi%2Fmockserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamshi%2Fmockserver/lists"}