<commit_before># Yadda
[![Build Status](https://travis-ci.org/acuminous/yadda.png)](https://travis-ci.org/acuminous/yadda)

Yadda brings _true_ BDD to JavaScript test frameworks such as [Jasmine](http://pivotal.github.io/jasmine/), [Mocha](http://visionmedia.github.io/mocha/), [QUnit](http://qunitjs.com), [Nodeunit](https://github.com/caolan/nodeunit), [WebDriverJs](code.google.com/p/selenium/wiki/WebDriverJs) and [CasperJS](http://casperjs.org). By _true_ BDD we mean that the ordinary language (e.g. English) steps are mapped to code, as opposed to simply decorating it. This is important because just like comments, the decorative steps such as those used by
[Jasmine](http://pivotal.github.com/jasmine), [Mocha](http://visionmedia.github.io/mocha) and [Vows](http://vowsjs.org), can fall out of date and are a form of duplication.

Yadda's BDD implementation is like [Cucumber's](http://cukes.info/) in that it maps the ordinary language steps to code. Not only are the steps less likely to go stale, but they also provide a valuable abstraction layer and encourage re-use. You could of course just use [CucumberJS](https://github.com/cucumber/cucumber-js), but we find Yadda less invasive and prefer it's flexible syntax to Gherkin's. Yadda's conflict resolution is smarter too.

## Installation
Yadda 0.8.0 is the current verison. It contains breaking changes to Yadda.localisation.English that were required to localise Feature files.
 ```js
// Old Code (< 0.8.0)
var library = new Yadda.localisation.English(optional_dictionary);

// After  (>= 0.8.0)
var library = Yadda.localisation.English.library(optional_dictionary);
```

### Node based environments (e.g. Mocha)
```
npm install yadda
```
### Browser based environments (e.g. QUnit)
```html
<script src="./lib/yadda-0.8.0.js"></script>
```
## Writing Yadda Tests
### Step 1 - Write your scenarios
bottles.feature
```
Feature: 100 Green Bottles

Scenario: should fall from the wall

   Given 100 green bottles are standing on the wall
   When 1 green bottle accidentally falls
   Then there are 99 green bottles standing on the wall

@Pending
Scenario: No bottles are left

    Given 1 green bottles are standing on the wall
    when 1 green bottle accidentally falls
    then there are 0 green bottles standing on the wall
```
### Step 2 - Implement the step library
bottles-library.js
```js
var assert = require('assert');
var English = require('yadda').localisation.English;

module.exports = (function() {
  var library = English.library()
    .given("$NUM green bottles are standing on the wall", function(number, next) {
       wall = new Wall(number);
       next();
    })
    .when("$NUM green bottle accidentally falls", function(number, next) {
       wall.fall(number);
       next();
    })
    .then("there are $NUM green bottles standing on the wall", function(number, next) {
       assert.equal(number, wall.bottles);
       next();
    });
})();
```
(If your test runner & code are synchronous you can omit the calls to 'next')


### Step 3 - Integrate Yadda with your testing framework (e.g. Mocha)
bottles-test.js
```js
var Yadda = require('yadda');
Yadda.plugins.mocha();

feature('./bottles.feature', function(feature) {

  var library = require('./bottles-library');
  var yadda = new Yadda.Yadda(library);

  scenarios(feature.scenarios, function(scenario, done) {
    yadda.yadda(scenario.steps, done);
  });
});
```

### Step 4 - Run your tests
```
  mocha --reporter spec bottles-test.js

  100 Green Bottles
    ✓ should fall from the wall
    - No bottles are left
```

## Features
### Supported Libraries
Yadda works with Mocha, Jasmine, QUnit, Nodeunit, ZombieJS, CasperJS and WebDriver. See the examples for details.

### Flexible BDD Syntax
It's common for BDD libraries to limit syntax to precondition (given) steps, action (when) steps and assertion (then) steps. Yadda doesn't. This allows for more freedom of expression. e.g.
```js
var library = new Yadda.Library()
    .define("$NUM green bottle(?:s){0,1} standing on the wall", function(number) {
        // some code
    })
    .define("if $NUM green bottle(?:s){0,1} should accendentally fall", function(number) {
        // some code
    })
    .define("there are $NUM green bottle(?:s){0,1} standing on the wall", function(number) {
        // some code
    });
new Yadda.yadda(library).yadda([
    "100 green bottles standing on the wall",
    "if 1 green bottle should accidentally fall",
    "there are 99 green bottles standing on the wall"
]);
```
However we think that Given/When/Then (along with And/But/With/If) is a good starting point, so we recommend using Yadda.localisation.English instead of the vanilla Yadda.Library. This adds 'given', 'when' and 'then' helper methods, enabling you to define your steps as follows...
```js
var library = new Yadda.Library()
    .given("$NUM green bottle(?:s){0,1} standing on the wall", function(number) {
        // some code
    })
    .when("$NUM green bottle(?:s){0,1} should accendentally fall", function(number) {
        // some code
    })
    .then("there are $NUM green bottle(?:s){0,1} standing on the wall", function(number) {
        // some code
    });
new Yadda.yadda(library).yadda([
    "Given 100 green bottles standing on the wall",
    "when 1 green bottle should accidentally fall",
    "then there are 99 green bottles standing on the wall"
]);
```
Because the localisatised definitions for 'given', 'when' and 'then' are loose you could also re-write the above scenario as
```js
new Yadda.yadda(library).yadda([
    "given 100 green bottles standing on the wall",
    "but 1 green bottle should accidentally fall",
    "expect there are 99 green bottles standing on the wall"
]);
```
We'd be delighted to accept pull requests for more languages and dialects.

### Feature Descriptions
You can add an optional feature description at the top of your file to give some context about the scenarios contained within
bottles.feature
```
Feature: As a bystander,
I can watch bottles falling from a wall
so that I can be mildly amused

Scenario: should fall from the wall

   Given 100 green bottles are standing on the wall
   When 1 green bottle accidentally falls
   Then there are 99 green bottles standing on the wall
```

There can only be a single feature present in a file - it really doesn't make sense to have two, and you will be issued with an error if you try to include more than one.

### Annotations
Annotations can be added to a feature or scenario to enable you to do any kind of pre-processing required.  These take the form of either single value tags or key/value pairs and can be added like this:

bottles.feature
```
@Browser=chrome
@Theme=bottles

Feature: As a bystander
    I can watch bottles falling from a wall
    So that I can be mildly amused

@Pending
Scenario: should fall from the wall

   Given 100 green bottles are standing on the wall
   When 1 green bottle accidentally falls
   Then there are 99 green bottles standing on the wall
```

### Comments
You can add single line or block comments too.
bottles.feature
```
###
  This
  is
  a
  block
  comment
###
Feature: As a bystander<commit_msg>Fixing travis png<commit_after># Yadda
[![Build Status](https://travis-ci.org/acuminous/yadda.png)](https://travis-ci.org/acuminous/yadda)

Yadda brings _true_ BDD to JavaScript test frameworks such as [Jasmine](http://pivotal.github.io/jasmine/), [Mocha](http://visionmedia.github.io/mocha/), [QUnit](http://qunitjs.com), [Nodeunit](https://github.com/caolan/nodeunit), [WebDriverJs](code.google.com/p/selenium/wiki/WebDriverJs) and [CasperJS](http://casperjs.org). By _true_ BDD we mean that the ordinary language (e.g. English) steps are mapped to code, as opposed to simply decorating it. This is important because just like comments, the decorative steps such as those used by
[Jasmine](http://pivotal.github.com/jasmine), [Mocha](http://visionmedia.github.io/mocha) and [Vows](http://vowsjs.org), can fall out of date and are a form of duplication.

Yadda's BDD implementation is like [Cucumber's](http://cukes.info/) in that it maps the ordinary language steps to code. Not only are the steps less likely to go stale, but they also provide a valuable abstraction layer and encourage re-use. You could of course just use [CucumberJS](https://github.com/cucumber/cucumber-js), but we find Yadda less invasive and prefer it's flexible syntax to Gherkin's. Yadda's conflict resolution is smarter too.

## Installation
Yadda 0.8.0 is the current verison. It contains breaking changes to Yadda.localisation.English that were required to localise Feature files.
 ```js
// Old Code (< 0.8.0)
var library = new Yadda.localisation.English(optional_dictionary);

// After  (>= 0.8.0)
var library = Yadda.localisation.English.library(optional_dictionary);
```

### Node based environments (e.g. Mocha)
```
npm install yadda
```
### Browser based environments (e.g. QUnit)
```html
<script src="./lib/yadda-0.8.0.js"></script>
```
## Writing Yadda Tests
### Step 1 - Write your scenarios
bottles.feature
```
Feature: 100 Green Bottles

Scenario: should fall from the wall

   Given 100 green bottles are standing on the wall
   When 1 green bottle accidentally falls
   Then there are 99 green bottles standing on the wall

@Pending
Scenario: No bottles are left

    Given 1 green bottles are standing on the wall
    when 1 green bottle accidentally falls
    then there are 0 green bottles standing on the wall
```
### Step 2 - Implement the step library
bottles-library.js
```js
var assert = require('assert');
var English = require('yadda').localisation.English;

module.exports = (function() {
  var library = English.library()
    .given("$NUM green bottles are standing on the wall", function(number, next) {
       wall = new Wall(number);
       next();
    })
    .when("$NUM green bottle accidentally falls", function(number, next) {
       wall.fall(number);
       next();
    })
    .then("there are $NUM green bottles standing on the wall", function(number, next) {
       assert.equal(number, wall.bottles);
       next();
    });
})();
```
(If your test runner & code are synchronous you can omit the calls to 'next')


### Step 3 - Integrate Yadda with your testing framework (e.g. Mocha)
bottles-test.js
```js
var Yadda = require('yadda');
Yadda.plugins.mocha();

feature('./bottles.feature', function(feature) {

  var library = require('./bottles-library');
  var yadda = new Yadda.Yadda(library);

  scenarios(feature.scenarios, function(scenario, done) {
    yadda.yadda(scenario.steps, done);
  });
});
```

### Step 4 - Run your tests
```
  mocha --reporter spec bottles-test.js

  100 Green Bottles
    ✓ should fall from the wall
    - No bottles are left
```

## Features
### Supported Libraries
Yadda works with Mocha, Jasmine, QUnit, Nodeunit, ZombieJS, CasperJS and WebDriver. See the examples for details.

### Flexible BDD Syntax
It's common for BDD libraries to limit syntax to precondition (given) steps, action (when) steps and assertion (then) steps. Yadda doesn't. This allows for more freedom of expression. e.g.
```js
var library = new Yadda.Library()
    .define("$NUM green bottle(?:s){0,1} standing on the wall", function(number) {
        // some code
    })
    .define("if $NUM green bottle(?:s){0,1} should accendentally fall", function(number) {
        // some code
    })
    .define("there are $NUM green bottle(?:s){0,1} standing on the wall", function(number) {
        // some code
    });
new Yadda.yadda(library).yadda([
    "100 green bottles standing on the wall",
    "if 1 green bottle should accidentally fall",
    "there are 99 green bottles standing on the wall"
]);
```
However we think that Given/When/Then (along with And/But/With/If) is a good starting point, so we recommend using Yadda.localisation.English instead of the vanilla Yadda.Library. This adds 'given', 'when' and 'then' helper methods, enabling you to define your steps as follows...
```js
var library = new Yadda.Library()
    .given("$NUM green bottle(?:s){0,1} standing on the wall", function(number) {
        // some code
    })
    .when("$NUM green bottle(?:s){0,1} should accendentally fall", function(number) {
        // some code
    })
    .then("there are $NUM green bottle(?:s){0,1} standing on the wall", function(number) {
        // some code
    });
new Yadda.yadda(library).yadda([
    "Given 100 green bottles standing on the wall",
    "when 1 green bottle should accidentally fall",
    "then there are 99 green bottles standing on the wall"
]);
```
Because the localisatised definitions for 'given', 'when' and 'then' are loose you could also re-write the above scenario as
```js
new Yadda.yadda(library).yadda([
    "given 100 green bottles standing on the wall",
    "but 1 green bottle should accidentally fall",
    "expect there are 99 green bottles standing on the wall"
]);
```
We'd be delighted to accept pull requests for more languages and dialects.

### Feature Descriptions
You can add an optional feature description at the top of your file to give some context about the scenarios contained within
bottles.feature
```
Feature: As a bystander,
I can watch bottles falling from a wall
so that I can be mildly amused

Scenario: should fall from the wall

   Given 100 green bottles are standing on the wall
   When 1 green bottle accidentally falls
   Then there are 99 green bottles standing on the wall
```

There can only be a single feature present in a file - it really doesn't make sense to have two, and you will be issued with an error if you try to include more than one.

### Annotations
Annotations can be added to a feature or scenario to enable you to do any kind of pre-processing required.  These take the form of either single value tags or key/value pairs and can be added like this:

bottles.feature
```
@Browser=chrome
@Theme=bottles

Feature: As a bystander
    I can watch bottles falling from a wall
    So that I can be mildly amused

@Pending
Scenario: should fall from the wall

   Given 100 green bottles are standing on the wall
   When 1 green bottle accidentally falls
   Then there are 99 green bottles standing on the wall
```

### Comments
You can add single line or block comments too.
bottles.feature
```
###
  This is  a
  block comment
###
Feature: As a bystander
{'fraction_non_alphanumeric': 0.10713038620015364, 'fraction_numerical': 0.010196242754382289, 'mean_word_length': 3.841108857336038, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 8, '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': '7496275', 'n_tokens_mistral': 4389, 'n_tokens_neox': 4123, 'n_words': 1757}