<commit_before>Storage and execution API for Ludwig, the collaborative testing tool
====================================================================

> API de stockage et d'exécution de l'outil de test collaboratif Ludwig.


[![Build Status](https://secure.travis-ci.org/sgmap/ludwig-api.svg)](http://travis-ci.org/sgmap/ludwig-api)
[![Dependency Status](https://david-dm.org/sgmap/ludwig-api.svg)](https://david-dm.org/sgmap/ludwig-api)
[![Dev Dependency status](https://david-dm.org/sgmap/ludwig-api/dev-status.svg)](https://david-dm.org/sgmap/ludwig-api#info=devDependencies&view=table)
[![Code Climate](https://codeclimate.com/github/sgmap/ludwig-api/badges/gpa.svg)](https://codeclimate.com/github/sgmap/ludwig-api)
[![Test Coverage](https://codeclimate.com/github/sgmap/ludwig-api/badges/coverage.svg)](https://codeclimate.com/github/sgmap/ludwig-api)


Usage
-----

Add `ludwig-api: "sgmap/ludwig-api"` as a dependency in your `package.json`, and then `require` it.

The `ludwig-api` module exports a single function that takes a single configuration object as a parameter and returns an [Express](http://expressjs.com) middleware.
This means you should use it somehow like this: `app.use('/api', require('ludwig-api')(apiConf))`, with `app` being an Express app and `apiConf` an object with values as follow.

- `mongoose`: optional, if you want to reuse an existing Mongoose connection. If not, you will need to set the `MONGODB_URL` environment variable and have it point to a running MongoDB instance.
- `simulate`: an async function that takes two params: the `test` object as stored in the database and a callback. You will have to call the callback with an error as the first parameter, and the execution result as the second.
- `onCreate`: an opportunity to do something to a test when it is created. An async function that takes two params: the `test` object that is about to be stored in the database and a callback. You will have to call the callback with an error as the first parameter, and the possibly-transformed `test` object as the second. **Optional**, defaults to doing nothing.


### Fill the database

To manage tests, you will need to fill the `Users` collection.
The easiest way to do this is to define them in JSON in `fixtures/User.json`, and then run `npm run load-fixtures`.

If you want to add tests directly through shell, the name of the collection storing the tests is `AcceptanceTest`. Its schema is defined in `lib/models`.


Configuration
-------------

### Possible values

 In order to display human-readable results, you have to define the possible values that will be computed by the API.

- `id`: the value identifier that will be computed by the `simulate` function.
- `label`: a complete label that will be displayed to the user.
- `shortLabel`: a shorter label for the user to be used in table layouts.
- `hasMontant`: boolean. Set to `true` if the expected value is a number, set to `false` otherwise.


Authentication
--------------

Only logged-in users may filter and modify tests.<commit_msg>Improve documentation of possibleValues<commit_after>Storage and execution API for Ludwig, the collaborative testing tool
====================================================================

> API de stockage et d'exécution de l'outil de test collaboratif Ludwig.


[![Build Status](https://secure.travis-ci.org/sgmap/ludwig-api.svg)](http://travis-ci.org/sgmap/ludwig-api)
[![Dependency Status](https://david-dm.org/sgmap/ludwig-api.svg)](https://david-dm.org/sgmap/ludwig-api)
[![Dev Dependency status](https://david-dm.org/sgmap/ludwig-api/dev-status.svg)](https://david-dm.org/sgmap/ludwig-api#info=devDependencies&view=table)
[![Code Climate](https://codeclimate.com/github/sgmap/ludwig-api/badges/gpa.svg)](https://codeclimate.com/github/sgmap/ludwig-api)
[![Test Coverage](https://codeclimate.com/github/sgmap/ludwig-api/badges/coverage.svg)](https://codeclimate.com/github/sgmap/ludwig-api)


Usage
-----

Add `ludwig-api: "sgmap/ludwig-api"` as a dependency in your `package.json`, and then `require` it.

The `ludwig-api` module exports a single function that takes a single configuration object as a parameter and returns an [Express](http://expressjs.com) middleware.
This means you should use it somehow like this: `app.use('/api', require('ludwig-api')(apiConf))`, with `app` being an Express app and `apiConf` an object with values as follow.

- `mongoose`: optional, if you want to reuse an existing Mongoose connection. If not, you will need to set the `MONGODB_URL` environment variable and have it point to a running MongoDB instance.
- `simulate`: an async function that takes two params: the `test` object as stored in the database and a callback. You will have to call the callback with an error as the first parameter, and the execution result as the second.
- `onCreate`: an opportunity to do something to a test when it is created. An async function that takes two params: the `test` object that is about to be stored in the database and a callback. You will have to call the callback with an error as the first parameter, and the possibly-transformed `test` object as the second. **Optional**, defaults to doing nothing.


### Fill the database

To manage tests, you will need to fill the `Users` collection.
The easiest way to do this is to define them in JSON in `fixtures/User.json`, and then run `npm run load-fixtures`.

If you want to add tests directly through shell, the name of the collection storing the tests is `AcceptanceTest`. Its schema is defined in `lib/models`.


Configuration
-------------

### Possible values

In order to display human-readable results, you have to define the possible values that will be computed by the API.
These values are passed with the `possibleValues` option, as an array of objects with the following properties:

- `id`: the value identifier that will be computed by the `simulate` function.
- `label`: a complete label that will be displayed to the user.
- `shortLabel`: a shorter label for the user to be used in table layouts.
- `hasMontant`: boolean. Set to `true` if the expected value is a number, set to `false` otherwise.


Authentication
--------------

Only logged-in users may filter and modify tests.
{'fraction_non_alphanumeric': 0.1285462413848373, 'fraction_numerical': 0.0, 'mean_word_length': 4.435540069686411, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 18, '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': '5028833', 'n_tokens_mistral': 1789, 'n_tokens_neox': 1728, 'n_words': 755}