<commit_before># raf-stub

[![Build Status](https://travis-ci.org/alexreardon/raf-stub.svg?branch=master)](https://travis-ci.org/alexreardon/raf-stub)
[![Code coverage](https://codecov.io/github/alexreardon/raf-stub/coverage.svg)](https://codecov.io/gh/alexreardon/raf-stub)

Accurate and predictable testing of `requestAnimationFrame` and `cancelAnimationFrame`.

This is **not** designed to be a polyfill and is only intended for testing code.

## Basic usage

```js
// assuming node running environment so 'global' is the global object

import createStub from 'raf-stub';

const render = () => {
    return requestAnimationFrame(() => {
        console.log('animate allthethings!');
    });
}

describe('stub', () => {
    const stub = createStub();

    beforeEach(() => {
        sinon.stub(global, 'requestAnimationFrame', stub.add);
    });

    afterEach(() => {
        stub.reset();
        global.requestAnimationFrame.restore();
    });

    it('should allow us to execute requestAnimationFrame when we want', () => {
        render();

        stub.step();

        // console.log => animate allthethings!
    });

    it('should allow us to cancel requestAnimationFrame when we want', () => {
        var id = render();

        stub.remove(id);
        stub.step();

        // *crickets*
    });
});
```

### Stub existing `requestAnimationFrame`
(similar to the 'basic usage' example but replaces `requestAnimationFrame` and `cancelAnimationFrame` with a stub)
```js
import {enhance} from 'raf-stub';

// override requestAnimationFrame and cancelAnimationFrame with a stub
enhance();

const render = () => {
    return requestAnimationFrame(() => {
        console.log('animate allthethings!');
    });
}

describe('stub', () => {
    it('should allow us to execute requestAnimationFrame when we want', () => {
        render();

        requestAnimationFrame.step();

        // console.log => animate allthethings!
    });

    it('should allow us to cancel requestAnimationFrame when we want', () => {
        var id = render();

        cancelAnimationFrame(id);
        requestAnimationFrame.step();

        // *crickets*
    });
});
```

## Installation

```
npm i --save-dev raf-stub
```

## Stub

An isolated mock that contains it's own state. Each `stub` is independent and have it's own state.

### `createStub() => Stub`
```js
import createStub from 'raf-stub';

const stub = createStub();
```

### `.add(callback) => Int`

Same api as `requestAnimationFrame`. It schedules the callback to be called in the next frame.
It returns an `id` that can be used to cancel the frame in the future.
Callbacks will *not* automatically get called after a period of time. You need to explicitly release it using `step()` or `flush()`

```js
const stub = createStub();
const callback = () => {};

stub.add(callback);
```

### `.remove(id)`

Same api as `cancelAnimationFrame`. It takes the id of a `add()` call and cancels it.

```js
const stub = createStub();
const callback = () => {};

stub.add(callback);

// remove callback from the current frame
stub.remove(callback);
```

### `.step(?steps=1)`

Executes all callbacks in the current frame. You can optionally provide the amount of frames you would like to release. This becomes useful when you have nested calls

**Simple example**
```js
const callback1 = () => console.log('first callback');
const callback2 = () => console.log('second callback');
const stub = createStub();

stub.add(callback1);
stub.add(callback2);
stub.step();

// console.log => 'first callback'
// console.log => 'second callback'

```

**Nested example**

Some times calls to `requestAnimationFrame` themselves call `requestAnimationFrame`. `step()` will let you step through them one at a time.

```js
// this example will use the 'enhance' syntax as it is a little clearer

const callback = () => {
    console.log('first callback')

    // second frame
    requestAnimationFrame(() => console.log('second callback'));
};

requestAnimationFrame(callback);
// release the first frame
api.step();

// console.log => 'first callback'

// release the second frame
requestAnimationFrame.step();<commit_msg>fixing documentation example<commit_after># raf-stub

[![Build Status](https://travis-ci.org/alexreardon/raf-stub.svg?branch=master)](https://travis-ci.org/alexreardon/raf-stub)
[![Code coverage](https://codecov.io/github/alexreardon/raf-stub/coverage.svg)](https://codecov.io/gh/alexreardon/raf-stub)

Accurate and predictable testing of `requestAnimationFrame` and `cancelAnimationFrame`.

This is **not** designed to be a polyfill and is only intended for testing code.

## Basic usage

```js
// assuming node running environment so 'global' is the global object

import createStub from 'raf-stub';

const render = () => {
    return requestAnimationFrame(() => {
        console.log('animate allthethings!');
    });
}

describe('stub', () => {
    const stub = createStub();

    beforeEach(() => {
        sinon.stub(global, 'requestAnimationFrame', stub.add);
    });

    afterEach(() => {
        stub.reset();
        global.requestAnimationFrame.restore();
    });

    it('should allow us to execute requestAnimationFrame when we want', () => {
        render();

        stub.step();

        // console.log => animate allthethings!
    });

    it('should allow us to cancel requestAnimationFrame when we want', () => {
        var id = render();

        stub.remove(id);
        stub.step();

        // *crickets*
    });
});
```

### Stub existing `requestAnimationFrame`
(similar to the 'basic usage' example but replaces `requestAnimationFrame` and `cancelAnimationFrame` with a stub)
```js
import {enhance} from 'raf-stub';

// override requestAnimationFrame and cancelAnimationFrame with a stub
enhance();

const render = () => {
    return requestAnimationFrame(() => {
        console.log('animate allthethings!');
    });
}

describe('stub', () => {
    it('should allow us to execute requestAnimationFrame when we want', () => {
        render();

        requestAnimationFrame.step();

        // console.log => animate allthethings!
    });

    it('should allow us to cancel requestAnimationFrame when we want', () => {
        var id = render();

        cancelAnimationFrame(id);
        requestAnimationFrame.step();

        // *crickets*
    });
});
```

## Installation

```
npm i --save-dev raf-stub
```

## Stub

An isolated mock that contains it's own state. Each `stub` is independent and have it's own state.

### `createStub() => Stub`
```js
import createStub from 'raf-stub';

const stub = createStub();
```

### `.add(callback) => Int`

Same api as `requestAnimationFrame`. It schedules the callback to be called in the next frame.
It returns an `id` that can be used to cancel the frame in the future.
Callbacks will *not* automatically get called after a period of time. You need to explicitly release it using `step()` or `flush()`

```js
const stub = createStub();
const callback = () => {};

stub.add(callback);
```

### `.remove(id)`

Same api as `cancelAnimationFrame`. It takes the id of a `add()` call and cancels it.

```js
const stub = createStub();
const callback = () => {};

stub.add(callback);

// remove callback from the current frame
stub.remove(callback);
```

### `.step(?steps=1)`

Executes all callbacks in the current frame. You can optionally provide the amount of frames you would like to release. This becomes useful when you have nested calls

**Simple example**
```js
const callback1 = () => console.log('first callback');
const callback2 = () => console.log('second callback');
const stub = createStub();

stub.add(callback1);
stub.add(callback2);
stub.step();

// console.log => 'first callback'
// console.log => 'second callback'

```

**Nested example**

Some times calls to `requestAnimationFrame` themselves call `requestAnimationFrame`. `step()` will let you step through them one at a time.

```js
// this example will use the 'enhance' syntax as it is a little clearer
const callback = () => {
    console.log('first callback')

    // second frame
    requestAnimationFrame(() => console.log('second callback'));
};

requestAnimationFrame(callback);

// release the first frame
requestAnimationFrame.step();

// console.log => 'first callback'

// release the second frame
requestAnimationFrame.step();
{'fraction_non_alphanumeric': 0.1468506298740252, 'fraction_numerical': 0.0011997600479904018, 'mean_word_length': 3.628539700166574, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 53, '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': '2031704', 'n_tokens_mistral': 2432, 'n_tokens_neox': 2379, 'n_words': 783}