<commit_before>milli
=====
[![Build Status](https://travis-ci.org/kelveden/milli.png?branch=master)](https://travis-ci.org/kelveden/milli)
[![Dependencies Status](https://david-dm.org/kelveden/milli.png?branch=master)](https://david-dm.org/kelveden/milli)

A Javascript fluent API for use with https://github.com/kelveden/vanilli.

Installation
------------
milli is a single library with no dependencies. You can either pull the latest from the source `build` folder or install with bower:

	bower install milli

Usage
-----
milli manifests itself as a global singleton `milli`.

As milli talks to vanilli via the latter's REST API, milli is used in an asynchronous manner. A high-level view of usage (Mocha is the test framework that is used but milli has no explicit ties to it):

	beforeEach(function (done) {
		milli.clearStubs(done);
	});

	afterEach(function (done) {
		milli.verifyExpectations(done);
	});

	...

	it("does something", function (done) {
		milli
			.stub(stub1, stub2, ... , stubX)
			.expect(expectation1, expectation2, ... , expectationX)
			.run(function () {
				// Test stuff
			});
	});

	...

So, what's going on here? You can probably spot that there are several distinct steps:

1. Clear down any stubs from previous tests
2. Setup zero or more stubs
3. Setup zero or more expectations
4. Run test code
5. Verify that any expectations specified have been met

API
---
### milli.stub(s1, s2, ..., sX)
Tells milli about one or more stubs. A simple stub might look like:

    milli.stub(
        onGet("my/url")
            .param("queryparam1", "matchthisvalue")
            .respondWith(200)
            .entity("some content", "text/plain");

This stub would only be matched against a GET request to "/my/url" that included the query parameter `queryparam1=matchthisvalue`. For more information see the section on
"Stubs and Expectations" below.

### milli.expect(e1, e2, ..., eX)
Tells milli about one or more expectations. Setting up an expectation looks exactly the same as setting up a stub except that there is the extra option of
specifying the number of times that the stub is expected to be invoked.

### milli.run(callback)
Causes milli to submit all stubs and expectations setup via the asynchronous `stub` to vanilli. The specified callback is then executed. It is not necessary to run this when using milli synchronously.

### milli.verifyExpectations([doneCallback])
Verifies that all expectations setup via `expect` have been met. If expectations have not been met, the doneCallback argument is called passing in a new Error object to it as the first argument; otherwise the doneCallback is called with no arguments.

### milli.configure(config)
Allows the configuration of milli. See the 'Configuration' section below for more information.

### milli.clearStubs(doneCallback)
Tells vanilli to clear down all stubs and expectations. After this is done, the specified `doneCallback` is executed.

### milli.getCapture(captureId, doneCallback)
Retrieves the details of the specified capture. The result is passed to the specified `doneCallback`.

Stubs
-----
A stub contains all the information that vanilli needs to match against an incoming HTTP request. If vanilli matches an
incoming HTTP request against a stub it will respond with the response specified against that stub.

The matching algorithm is lazy in the sense that whilst ALL criteria specifed in the stub MUST be matched against a request, beyond that
it is irrelevant what other data is in the request. E.g. if there are querystring parameters in the request that are not
explicitly mentioned in the stub, the stub will still match.

A new stub is created via one of the `onXXX` functions exposed globally by milli - where 'XXX' is
an HTTP method (e.g. `onGet`). Each one of these functions returns a new stub builder that exposes a fluent API for crafting HTTP request
criteria to match the stub against.

The minimum that milli/vanilli need to know is the URL to match against and what status code to respond with; e.g.:

    milli.stub(onGet("my/url")).respondWith(200));

However, there are plenty of other criteria to match against on the stub builder API:

### Stub Builder API
#### Stub.body(body)
Match against a specific request body regex.

#### Stub.contentType(contentType)
Match against a specific Content-Type header; equivalent to `Stub.header("Content-Type", value)`;

#### Stub.entity(body, contentType)
Convenience function equivalent to `Stub.body(body).contentType(contentType)`;

#### Stub.header(name, value)
Match against a specific header with value regex.

#### Stub.param(name, value)
Match against a specific querystring parameter with value regex.

#### Stub.capture(captureId)
Instructs milli to capture the content of the request matched against the stub by logging it with the specified `captureId`. This id can
then be used with `milli.getCapture(captureId)` to retrieve the captured details.

#### Stub.respondWith(status)
Instructs milli to respond with the specified status when an incoming request matched against the stub. Returns a builder that<commit_msg>README updates.<commit_after>milli
=====
[![Build Status](https://travis-ci.org/kelveden/milli.png?branch=master)](https://travis-ci.org/kelveden/milli)
[![Dependencies Status](https://david-dm.org/kelveden/milli.png?branch=master)](https://david-dm.org/kelveden/milli)

A Javascript fluent API for use with https://github.com/kelveden/vanilli.

Installation
------------
milli is a single library with no dependencies. You can either pull the latest from the source `build` folder or install with bower:

	bower install milli

Usage
-----
milli manifests itself as a global singleton `milli`.

As milli talks to vanilli via the latter's REST API, milli is used in an asynchronous manner. A high-level view of usage (Mocha is the test framework that is used but milli has no explicit ties to it):

	beforeEach(function (done) {
		milli.clearStubs(done);
	});

	afterEach(function (done) {
		milli.verifyExpectations(done);
	});

	...

	it("does something", function (done) {
		milli
			.stub(stub1, stub2, ... , stubX)
			.expect(expectation1, expectation2, ... , expectationX)
			.run(function () {
				// Test stuff
			});
	});

	...

So, what's going on here? You can probably spot that there are several distinct steps:

1. Clear down any stubs from previous tests
2. Setup zero or more stubs
3. Setup zero or more expectations
4. Run test code
5. Verify that any expectations specified have been met

API
---
### milli.stub(s1, s2, ..., sX)
Tells milli about one or more stubs. A simple stub might look like:

    milli.stub(
        onGet("my/url")
            .param("queryparam1", "matchthisvalue")
            .respondWith(200)
            .entity("some content", "text/plain");

This stub would only be matched against a GET request to "/my/url" that included the query parameter `queryparam1=matchthisvalue`. For more information see the section on
"Stubs and Expectations" below.

### milli.expect(e1, e2, ..., eX)
Tells milli about one or more expectations. Setting up an expectation looks exactly the same as setting up a stub except that there is the extra option of
specifying the number of times that the stub is expected to be invoked.

### milli.run(callback)
Causes milli to submit all stubs and expectations setup via the asynchronous `stub` to vanilli. The specified callback is then executed. It is not necessary to run this when using milli synchronously.

### milli.verifyExpectations([doneCallback])
Verifies that all expectations setup via `expect` have been met. If expectations have not been met, the doneCallback argument is called passing in a new Error object to it as the first argument; otherwise the doneCallback is called with no arguments.

### milli.configure(config)
Allows the configuration of milli. See the 'Configuration' section below for more information.

### milli.clearStubs(doneCallback)
Tells vanilli to clear down all stubs and expectations. After this is done, the specified `doneCallback` is executed.

### milli.getCapture(captureId, doneCallback)
Retrieves the details of the specified capture. The result is passed to the specified `doneCallback`.

Stubs
-----
A stub contains all the information that vanilli needs to match against an incoming HTTP request. If vanilli matches an
incoming HTTP request against a stub it will respond with the response specified against that stub.

The matching algorithm is lazy in the sense that whilst ALL criteria specifed in the stub MUST be matched against a request, beyond that
it is irrelevant what other data is in the request. E.g. if there are querystring parameters in the request that are not
explicitly mentioned in the stub, the stub will still match.

A new stub is created via one of the `onXXX` functions exposed globally by milli - where 'XXX' is
an HTTP method (e.g. `onGet`). Each one of these functions returns a new stub builder that exposes a fluent API for crafting HTTP request
criteria to match the stub against.

The minimum that milli/vanilli need to know is the URL to match against and what status code to respond with; e.g.:

    milli.stub(onGet("my/url")).respondWith(200));

(Note that the url specified may be a string or a RegExp.) However, there are plenty of other criteria to match against on the stub builder API:

### Stub Builder API
#### Stub.body(body)
Match against a specific request body regex.

#### Stub.contentType(contentType)
Match against a specific Content-Type header; equivalent to `Stub.header("Content-Type", value)`;

#### Stub.entity(body, contentType)
Convenience function equivalent to `Stub.body(body).contentType(contentType)`;

#### Stub.header(name, value)
Match against a specific header with value. (Value may be a RegExp.)

#### Stub.param(name, value)
Match against a specific querystring parameter with value. (Value may be a RegExp.)

#### Stub.query(name, value)
Synnoym for `stub.param`. See above.

#### Stub.capture(captureId)
Instructs milli to capture the content of the request matched against the stub by logging it with the specified `captureId`. This id can
then be used with `milli.getCapture(captureId)` to retrieve the captured details.

#### Stub.respondWith(status)
Instructs milli to respond with the specified status when an incoming request matched against the stub. Returns a builder that
{'fraction_non_alphanumeric': 0.08608058608058608, 'fraction_numerical': 0.004048582995951417, 'mean_word_length': 4.221439355812783, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6972461', 'n_tokens_mistral': 2899, 'n_tokens_neox': 2802, 'n_words': 1349}