@mocks-server/main - npm Package Compare versions

Comparing version 1.1.0 to 1.1.1

CHANGELOG.md

		@@ -17,2 +17,6 @@ # Change Log

		## [1.1.1] - 2019-11-12
		### Changed
		- Change readme. Add links to docs website.

		## [1.1.0] - 2019-11-08
		@@ -19,0 +23,0 @@ ### Changed

package.json

		{
		"name": "@mocks-server/main",
		"version": "1.1.0",
		"version": "1.1.1",
		"description": "Mocks server with extensible fixtures groupables in predefined behaviors. Behavior can be changed using CLI or REST API",
		@@ -5,0 +5,0 @@ "keywords": [

224

README.md

		@@ -7,223 +7,23 @@ [![Build status][travisci-image]][travisci-url] [![Coverage Status][coveralls-image]][coveralls-url] [![Quality Gate][quality-gate-image]][quality-gate-url]

		# Mocks Server

		Mocks server with extensible fixtures groupables in predefined behaviors. Behavior can be changed using built-in CLI or REST API.
		# [![Mocks Server][logo-url]][website-url] Mocks Server

		## Getting Started
		This package provides a server that simulates API behaviors. It can be added as a dependency of your project, and started simply running an NPM command.

		This package provides a server that simulates API behaviors. As input, it needs "fixtures", which are responses for specific uris, and "behaviors", which are sets of "fixtures".
		## Documentation

		It also provide a built-in CLI and a REST API which allows to change the currently used "behavior" in any moment simply making an http request.
		Please refer to the [project documentation website][website-url]:

		## Installation
		* [Get started](https://www.mocks-server.org/docs/get-started-intro)
		* [Tutorials](https://www.mocks-server.org/docs/tutorials-static)
		* [configuration](https://www.mocks-server.org/docs/configuration-command-line-arguments)

		```bash
		npm i @mocks-server/main --save-dev
		```
		## Why a mocks server?

		## Usage
		Controlling the responses of the api will improve the front-end development workflow, avoiding early dependencies with back-end. It also improves the testing and development of error cases or another cases that are commonly hard to reproduce in the real api.

		Add an script to your `package.json` file, including the path to your mocks folder:
		Defining the api responses during the earliest phases of development will improve the communication among team members and align their expectations.

		```json
		"scripts": {
		"mocks-server" : "mocks-server --behaviors=./mocks"
		}
		```
		Working with Node.js, it integrates better in front-end projects as any other NPM dependency, and it will be easier for front-end developers to maintain the mocks.

		Now, you can start the mocks server CLI simply typing:

		```bash
		npm run mocks-server
		```

		![cli-home](./assets/cli_animation.gif)

		## Options

		* port `<Number>` Por number for the Server to be listening.
		* host `<String>` Host for the server. Default is "0.0.0.0" (Listen to any local host).
		* log `<String>` Logs level. Can be one of "silly", "debug", "verbose", "info", "warn", "error".
		* watch `<Boolean>` Watch behaviors folder, and restart server on changes. Default is `true`.
		* behavior `<String>` Selected behavior when server is started.
		* delay `<Number` Responses delay time in milliseconds.
		* behaviors `Path as <String>` Path to a folder containing behaviors to be used by the server.
		* recursive `<Boolean>` Load behaviors recursively. Watch is not affected by this option, it is always recursive.
		* cli `<Boolean>` Start interactive CLI. Default is `true`.

		## Defining mocks

		The Mocks server handles two main concepts for defining mocks:

		### Behaviors

		Each behavior consists in a set of "fixtures", which are server responses for specific uris.

		Behaviors are extensibles, so, you can have a "base" behavior, which defines the standard behavior of the mocks server and responses for all api uris, and change this behavior creating new behaviors that changes only responses for certain "uris". All extended behaviors are extensible as well.

		For creating a Behavior, you have to use the mocks-server "Behavior" class, providing an array of "fixtures" to it:

		```js
		// Behaviors file 1

		const { Behavior } = require("@mocks-server/main");

		const fixtures = require("./fixtures");

		const myBehavior = new Behavior([fixtures.uri_1_fixture, fixtures.uri_2_fixture]);

		module.exports = {
		myBehavior
		};
		```

		Now, when loaded, the server will have available a "myBehavior" behavior, which contains two fixtures. You can add more behaviors extending the first one and changing only the response for "uri_2", for example:

		```js
		// Behaviors file 2

		const { myBehavior } = require("./behaviors");

		const fixtures = require("./fixtures");

		const myBehavior2 = myBehavior.extend([fixtures.uri_2_different_fixture]);

		module.exports = {
		myBehavior2
		};
		```

		Now, server will have available "myBehavior" and "myBehavior2" behaviors. And "myBehavior2" will send a different response only for "uri_2" (supossing that "uri_2_fixture" and "uri_2_different_fixture" were defined with the same uri)

		### Fixtures

		A "fixture" defines the response for an specific uri. It has to be an object containing properties:

		* url `uri as <String>` Uri of the resource. It can contains expressions for matching dynamic uris. Read the [route-parser](https://www.npmjs.com/package/route-parser) documentation for further info about how to use dynamic routing.
		* method `<String>` Method of the request. Defines to which method will response this fixture. Valid values are http request methods, such as "GET", "POST", "PUT", etc.
		* response `<Object>` Defines the response that the Mocks Server will send to the request:
		* status `<Number>` Status code to send.
		* body `<Object>` Json object to send as body in the response.
		* response `<Function>` Response can be defined as a function too. The function will receive the [express](http://expressjs.com/es/api.html) `request`, `response` and `next` arguments, so you are free to handle the server request as you need.

		```js
		// Fixtures file

		// fixtures with static responses
		const uri_1_fixture = {
		url: "/api/foo-uri",
		method: "GET",
		response: {
		status: 200,
		body: [
		{
		name: "foo-name"
		}
		]
		}
		};

		const uri_2_fixture = {
		url: "/api/foo-uri-2/:id",
		method: "PUT",
		response: {
		status: 204
		}
		};

		// fixture with a dynamic response
		const uri_2_different_fixture = {
		url: "/api/foo-uri-2/:id",
		method: "PUT",
		response: (req, res) => {
		res.status(404);
		res.send({
		message: `${req.params.id} was not found`
		});
		}
		};

		module.exports = {
		uri_1_fixture,
		uri_2_fixture,
		uri_2_different_fixture
		};
		```

		## REST API

		The server includes a REST API that allows to change dinamically the current behavior, change delay time, etc. This is __very useful when running acceptance tests, as you can change the behavior of the api__ simply with a request in your tests `before` method.

		Available api resources are:

		* `GET` `/mocks/behaviors` Returns an array containing all available behaviors.
		* `GET` `/mocks/behaviors/current` Returns current behavior.
		* `PUT` `/mocks/behaviors/current` Set current behavior.
		* Request body example: `{ "name": "behavior-name" }`
		* `GET` `/mocks/settings` Return current server settings.
		* Response body example: `{ "delay": 0 }`
		* `PUT` `/mocks/settings` Change current server settings.
		* Request body example: `{ "delay": 3000 }`

		## Programmatic usage

		The server can be instantiated and started programmatically:

		```js
		const { Server } = require("@mocks-server/main");

		const startMyServer = () => {
		const server = new Server(path.resolve(__dirname, "mocks"), {
		port: 3200,
		log: "debug",
		watch: false
		});

		return server.start();
		};

		startMyServer().then(server => {
		console.log("Server started", server);
		});
		```

		#### `Server` (behaviorsFolder \[,options\])

		First argument is mandatory, and has to be a path to a folder containing "behaviors" and "fixtures". All files in the folder will be loaded recursively, including subfolders.
		For second argument options, please read the [options](#options) chapter of this documentation.

		Available methods of an instance are:

		- `start` (). Starts the server.
		- `stop` (). Stops the server.
		- `restart` (). Stops the server, initializes it again (reloading behaviors files), and starts it again.
		- `switchWatch` (state `<Boolean>`). Enable or disable behaviors files watch, depending of the received "state" value.

		Available getters are:

		- `behaviors`. Returns loaded behaviors object.
		- `watchEnabled`. Current state of the behaviors files watcher.
		- `error`. When server has returned an error, or an error ocurred loading behaviors, it is available in this property.
		- `events`. Returns server events object. A "watch-reload" event is emitted when the server watch detects changes in any behaviors or fixtures file, and restarts the server.

		> The interactive CLI can be started programatically too. Read the [cli advanced docs](./docs/cli.md) for further info.

		## Global usage

		The mocks server can be used as a global dependency as well:

		```bash
		npm i @mocks-server/main -g
		```

		Now, you can start the built-in command line interface from anywhere, providing a path to a folder containing behaviors:

		```bash
		mocks-server --behaviors=./path-to-behaviors
		```

		## Support (OS Terminals)

		This package uses [inquirer][inquirer-url] for displaying CLI. You can [consult his OS Terminals support here][inquirer-support].

		## Contributing
		@@ -234,2 +34,4 @@

		[website-url]: https://www.mocks-server.org
		[logo-url]: https://www.mocks-server.org/img/logo_120.png
		[inquirer-url]: https://www.npmjs.com/package/inquirer#support-os-terminals
		@@ -236,0 +38,0 @@ [inquirer-support]: https://www.npmjs.com/package/inquirer#support-os-terminals

@mocks-server/main - npm Package Compare versions

Worsened metrics