You've sat down at your terminal, opened up a terminal and are ready to start debugging your new smart contract.

You type in nodeos, hit Enter and then see those cryptic words every EOSIO smart contract developer who has ever played around regularly with nodeos dreads:

nodeos replay required

Or, my personal favourite:

nodeos database dirty flag set

What in the....? You think. Why is the database dirty?

You start Googling and going through EOSIO Dev Telegram posts for a solution, all the while wondering how it suddenly became your job to be a part-time BP!

You figure out how to clean your dirty database, which will probably require you to completely wipe your local test net and reinitialise the state of your smart contract and all your local system contracts. And eventually you get your tests running.

Until it happens again.

"This is backwards," a little voice whispers inside of you. "There's got to be a better way."

And the truth is, yes you can write a bunch of shell scripts that will setup your test environment and have it working just the way you like it. While this is very flexible and allows quick prototyping, it takes some effort to create the scripts in the first place. It's like re-inventing the wheel and missing out on all of the advances in automated testing frameworks that run a suite of tests every time you make a code change.

What’s important in a test environment?

To get the most out of automated testing, it’s important that a testing framework supports the developer in 2 ways:


The testing framework should make it simple to write and run tests.
Specifically when testing EOSIO smart contracts, a testing framework should eliminate a lot of the tedious and repetitive tasks encountered when testing:

  1. Having to set up and maintain an EOSIO network
  2. Preparing the blockchain for the tests: Creating test accounts, managing private keys, setting up account permissions, setting the smart contract code, and bringing the blockchain into a testing state, e.g., by creating and issuing tokens
  3. Sending transactions and observing the outcome by checking contract tables or action traces

Repeatability / Determinism

The point of having automated tests is that they can be run anytime on code changes, for example, on the CI server whenever a team member commits new code to GitHub to ensure a change did not negatively affect existing features (regression testing). The tests need to be easily repeatable for every developer and run in the same blockchain environment every time. This usually means running the tests on a local or private EOSIO network that is fully controlled.

Public testnets can be problematic because the environment constantly changes and cannot be reset. One is at the mercy of the chain’s RAM/CPU/NET restrictions, token faucets, and might encounter unstable BPs experimenting with non-standard settings. Private testnets mean having to maintain and debug your nodeos installation and running on high-end machines.

Testing without nodeos

It is possible to run tests without directly connecting to an existing nodeos node. There are several test frameworks that do this by either running a stripped down nodeos version or not requiring running a node at all.

This removed overhead makes them great for writing unit tests and allows for more flexibility as they are not restricted by the node behaviour. On the other hand, one cannot use them for deploying and running tests on a real EOSIO network.


Hydra is one such testing framework that allows you to quickly get started writing unit tests.

Tests are written in JavaScript or TypeScript and allows you to use familiar JavaScript testing frameworks like Jest and Mocha.  In addition, it comes with some convenience features like bootstrapping test files, loading initial table contract data from JSON files, or being able to change the block time.

The reason it can do all this is that it runs on a customized EOSIO version (run by the Klevoya team) specifically designed for unit testing. Hydra therefore does not require any additional local setup at all, albeit it does need an internet connection.

This allows tests written in Hydra to be easily integrated into CI systems and the developer workflow. Along with its simple API and good documentation it's a great choice to test EOSIO smart contracts.

Check out Hydra

We hope this helps you see that there is an alternative to debugging those cryptic nodeos errors. Check out Hydra and see how easy it is to get testing!

For more details on how Hydra compares to nodeos+cleos, EOS Native Tester, EOSIO Unit Tests & Boost, or other EOSIO test frameworks, then download our EOSIO test framework comparison guide.