# ganache-time-traveler

> A ganache utility that simplifies writing time dependent or stateless tests on a local Ethereum blockchain.

Latest version **1.0.16** (published 2021-06-29) · ISC license · 0 weekly downloads

## Install

```sh
npm install ganache-time-traveler
pnpm add ganache-time-traveler
yarn add ganache-time-traveler
bun add ganache-time-traveler
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.16 |
| Published | 2021-06-29 |
| First published | 2019-07-17 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 45.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 48 |
| Author | ejwessel |
| Maintainers | ejwessel, brianchou |
| Keywords | ethereum, solidity, testing, truffle, ganache |

## Links

- npm: https://www.npmjs.com/package/ganache-time-traveler
- Repository: https://github.com/ejwessel/GanacheTimeTraveler
- Homepage: https://github.com/ejwessel/GanacheTimeTraveler#readme
- Issues: https://github.com/ejwessel/GanacheTimeTraveler/issues
- npm.io page: https://npm.io/package/ganache-time-traveler

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 1.0.16 (latest) — 2021-06-29
- 1.0.15 — 2020-09-14
- 1.0.14 — 2020-03-14
- 1.0.13 — 2020-03-14
- 1.0.12 — 2020-03-14
- 1.0.11 — 2019-12-09
- 1.0.10 — 2019-11-19
- 1.0.9 — 2019-11-19
- 1.0.8 — 2019-11-19
- 1.0.7 — 2019-11-19
- 1.0.6 — 2019-11-19
- 1.0.5 — 2019-08-17
- 1.0.4 — 2019-08-17
- 1.0.3 — 2019-08-10
- 1.0.2 — 2019-07-26
- … 2 more at https://npm.io/package/ganache-time-traveler/versions

## README

<img width="20%" height="20%" src="https://raw.githubusercontent.com/ejwessel/GanacheTimeTraveler/master/blackhole.png">

 
# ganache-time-traveler
A ganache utility that simplifies writing time dependent or stateless tests on a local Ethereum blockchain.

- [Read my Medium Post](https://medium.com/fluidity/standing-the-time-of-test-b906fcc374a9)

- [Watch my Presentation](https://photos.app.goo.gl/6qkd5AN2BthxkY2K6)

- [Time Contract Example](https://github.com/ejwessel/TimeContract)


NOTE:
- this only works with ganache-cli
- this only works locally

## Tool Dependencies
- [ganache-cli](https://github.com/trufflesuite/ganache-cli)
- [truffle](https://www.trufflesuite.com/docs/truffle/getting-started/installation)

## Install
- `npm i ganache-time-traveler`

## Usage
The general outline is to add `require` at the top of your tests
```javascript
const timeMachine = require('ganache-time-traveler');
```

add the `beforeEach` and `afterEach` hooks into your truffle test file
 ```javascript
contract('Test', async (accounts) =>  {

    let exampleContract;

    beforeEach(async() => {
        let snapshot = await timeMachine.takeSnapshot();
        snapshotId = snapshot['result'];
    });

    afterEach(async() => {
        await timeMachine.revertToSnapshot(snapshotId);
    });

    before('Deploy Contracts', async() => {
        /* DEPLOY CONTRACTS HERE */
        exampleContract = await ExampleContract.new();
    });

    /* ADD TESTS HERE */

    it('Time Dependent Test', async () => {
        await timeMachine.advanceTimeAndBlock(/* SECONDS TO ADVANCE BY */);
    });
});
 ```

## Methods
### `advanceTime(<seconds_to_advance_by>)`
Advances the time on the blockchain forward. Takes a single parameter, which is the number of seconds to advance by.
Note: for advancetime() to take effect, the block must also be mined using `advanceBlock()`. See `advanceTimeAndBlock()` to do both.

### `advanceBlock()`
Mines a new block; advances the block forward by 1 block.

### `advanceBlockAndSetTime(<new_time>)`
Advances the block forward by 1 and **sets** the time to a new time.

### `advanceTimeAndBlock(<seconds_to_advance_by>)`
Advances the block by 1 in addition to advancing the time on the blockchain forward. Takes a single parameter, which is the number of seconds to advance by.

### `takeSnapshot()`
Snapshot the state of the blockchain at the current block. Takes no parameters. Returns the integer id of the snapshot created.

### `revertToSnapshot(<id_to_revert_to>)`
Revert the state of the blockchain to a previous snapshot. Takes a single parameter, which is the snapshot id to revert to.

## Resources
- https://github.com/trufflesuite/ganache-cli
- https://www.trufflesuite.com
- [Icon created by Focus Lab from Noun Project](https://thenounproject.com/search/?q=space%20and%20time&i=547869)

---
_Source: https://npm.io/package/ganache-time-traveler · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._