<commit_before>
targaryen
=========

[![Build Status](https://travis-ci.org/goldibex/targaryen.svg)](https://travis-ci.org/goldibex/targaryen)

Completely and thoroughly test your Firebase security rules without connecting to Firebase.

## Usage

All you need to do is supply the security rules and some mock data, then write tests describing the expected behavior of the rules. Targaryen will interpret the rules and run the tests.

```js
const assert = require('assert');
const targaryen = require('targaryen');

const rules = {
  rules: {
    foo: {
      '.write': 'true'
    }
  }
};
const data = {foo: 1};
const auth = {uid: 'someuid'};

const database = targaryen.database(rules, data);
const {allowed, newDatabase, info} = database.as(auth).write('/foo', 2);

console.log('Rule evaluations:\n', info);
assert.ok(allowed);

assert.equal(newDatabase.rules, database.rules);
assert.equal(newDatabase.root.foo.$value(), 2);
assert.equal(newDatabase.auth, auth);
```

Targaryen provides three convenient ways to run tests:

- as a standalone command-line utility:

    ```bash
    targaryen path/to/rules.json path/to/tests.json
    ```

- as a set of custom matchers for [Jasmine](https://jasmine.github.io):

    ```js
    const targaryen = require('targaryen/plugins/jasmine');;

    describe('my security rules', function() {

      beforeEach(function() {
        jasmine.addMatchers(targaryen.matchers);
        targaryen.setFirebaseData(require(DATA_PATH));
        targaryen.setFirebaseRules(require(RULES_PATH));
      });

      it('should allow authenticated used to rule all data', function() {
        expect({uid: 'foo'}).canRead('/');
        expect(null).cannotRead('/');
      })

    });
    ```

- or as a plugin for [Chai](http://chaijs.com).

    ```js
    const chai = require('chai');
    const targaryen = require('targaryen/plugins/chai');
    const expect = chai.expect;

    chai.use(targaryen);

    describe('my security rules', function() {

      before(function() {
        targaryen.setFirebaseData(require(DATA_PATH)));
        targaryen.setFirebaseRules(require(RULES_PATH));
      });

      it('should allow authenticated used to rule all data', function() {
        expect({uid: 'foo'}).can.read.path('/');
        expect(null).cannot.read.path('/');
      })

    });
    ```

When a test fails, you get detailed debug information that explains why the read/write operation succeeded/failed.

See [USAGE.md](https://github.com/goldibex/targaryen/blob/master/USAGE.md) for more information.


## How does Targaryen work?

Targaryen statically analyzes your security rules using [esprima](http://esprima.org). It then conducts two passes over the abstract syntax tree. The first pass, during the parsing process, checks the types of variables and the syntax of the rules for correctness. The second pass, during the testing process, evaluates the expressions in the security rules given a set of state variables (the RuleDataSnapshots, auth data, the present time, and any wildchildren).

<commit_msg>Typo in usage code example<commit_after>
targaryen
=========

[![Build Status](https://travis-ci.org/goldibex/targaryen.svg)](https://travis-ci.org/goldibex/targaryen)

Completely and thoroughly test your Firebase security rules without connecting to Firebase.

## Usage

All you need to do is supply the security rules and some mock data, then write tests describing the expected behavior of the rules. Targaryen will interpret the rules and run the tests.

```js
const assert = require('assert');
const targaryen = require('targaryen');

const rules = {
  rules: {
    foo: {
      '.write': 'true'
    }
  }
};
const data = {foo: 1};
const auth = {uid: 'someuid'};

const database = targaryen.database(rules, data);
const {allowed, newDatabase, info} = database.as(auth).write('/foo', 2);

console.log('Rule evaluations:\n', info);
assert.ok(allowed);

assert.equal(newDatabase.rules, database.rules);
assert.equal(newDatabase.root.foo.$value(), 2);
assert.equal(newDatabase.auth, auth);
```

Targaryen provides three convenient ways to run tests:

- as a standalone command-line utility:

    ```bash
    targaryen path/to/rules.json path/to/tests.json
    ```

- as a set of custom matchers for [Jasmine](https://jasmine.github.io):

    ```js
    const targaryen = require('targaryen/plugins/jasmine');;

    describe('my security rules', function() {

      beforeEach(function() {
        jasmine.addMatchers(targaryen.matchers);
        targaryen.setFirebaseData(require(DATA_PATH));
        targaryen.setFirebaseRules(require(RULES_PATH));
      });

      it('should allow authenticated user to read all data', function() {
        expect({uid: 'foo'}).canRead('/');
        expect(null).cannotRead('/');
      })

    });
    ```

- or as a plugin for [Chai](http://chaijs.com).

    ```js
    const chai = require('chai');
    const targaryen = require('targaryen/plugins/chai');
    const expect = chai.expect;

    chai.use(targaryen);

    describe('my security rules', function() {

      before(function() {
        targaryen.setFirebaseData(require(DATA_PATH)));
        targaryen.setFirebaseRules(require(RULES_PATH));
      });

      it('should allow authenticated user to read all data', function() {
        expect({uid: 'foo'}).can.read.path('/');
        expect(null).cannot.read.path('/');
      })

    });
    ```

When a test fails, you get detailed debug information that explains why the read/write operation succeeded/failed.

See [USAGE.md](https://github.com/goldibex/targaryen/blob/master/USAGE.md) for more information.


## How does Targaryen work?

Targaryen statically analyzes your security rules using [esprima](http://esprima.org). It then conducts two passes over the abstract syntax tree. The first pass, during the parsing process, checks the types of variables and the syntax of the rules for correctness. The second pass, during the testing process, evaluates the expressions in the security rules given a set of state variables (the RuleDataSnapshots, auth data, the present time, and any wildchildren).


{'fraction_non_alphanumeric': 0.13191140278917146, 'fraction_numerical': 0.0009844134536505333, 'mean_word_length': 3.7662236121970287, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, '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': '1106287', 'n_tokens_mistral': 1886, 'n_tokens_neox': 1818, 'n_words': 542}