Neo-fairy-test is a set of tools designed to enhance the testing and debugging experience of Neo N3 smart contracts. Maintained by Neo blockchain developer Hecate2 and packaged as a plugin for NeoCLI, the solution allows developers to test transactions and smart contracts against real world network state.

Fairy operations

The test environment delivers a significantly different experience to Neo Express, which offers easy-to-deploy private networks. Instead, neo-fairy-test allows developers to send “fairy transactions” or deploy “fairy contracts” to their own modified version of public networks, such as MainNet or TestNet.

These operations are executed and stored in memory on the local node rather than published in MainNet blocks. This feature enables thorough testing against real world on-chain environments, without needing to re-deploy and set up code, incur gas fees, or make unintended changes to global state.


Another advantage of the tool is its ability to facilitate complete testing and debugging. With the DumpNef plugin, developers can leverage functionalities such as setting debug information, breakpoints, and invoking contracts via the debug API. This capability returns a detailed execution trace, making the debugging process more efficient.

The FairyEngine also allows fine-grained control over system time and random numbers. Controlling these usually dynamic values is especially convenient for developers interacting with time-locked smart contracts or debugging code made non-deterministic by randomness.


Provided alongside the practical tools is a comprehensive guide for debugging Neo N3. It uses Visual Studio to demonstrate how contract exceptions may be debugged down to the Neo source code level. The guide educates on many Neo core concepts to aid the developer, including elements such as remote nodes, transactions, blocks, verification, dBFT consensus, and more.

Finally, a Python client is also available, which may be used to simplify interactions with a Neo node running the Fairy plugin. The documentation shows how to use the client to call fairy contracts, clone snapshots, and perform debugging. It also includes sample usage scenarios, such as performing an NFT loan, illustrating the capabilities and applications of the tool.

Get started with neo-fairy-test at the link below: