Using EOSFactory With an Existing EOS Smart-Contract Project

The purpose of this tutorial is to demonstrate how to apply EOSFactory to an existing EOS smart-contract project with an arbitrary folder structure.


  • This tutorial assumes that you have successfully installed EOSFactory. If it’s not the case, please refer to Installing EOSFactory.

  • Your smart-contract project is located inside a folder named foo_project.

  • Your smart-contract’s C++ source code is contained in a file named foo_source.cpp, located anywhere inside the foo_project folder (it can also be located in a subfolder inside the foo_project folder).

  • If your project requires a C++ header file, it’s contained in a file named foo_header.hpp, located anywhere inside the foo_project folder (it can also be located in a subfolder inside the foo_project folder).

  • A test scenario for your contract is contained in a file named This file can be located anywhere you want - it doesn’t need to be inside the foo_project folder.

NOTE: Obviously, foo_project, foo_source, foo_header and foo_test are placeholders - they can be replaced by any names you prefer.

NOTE: We assume there is only one C++ source code file (i.e. an *.cpp file) within the foo_project folder. If your project for some reasons requires more than one *.cpp file, EOSFactory can handle this situation but it requires a more complex setup, which is beyond the scope of this guide.

Create a test script

A test scenario contained in the file needs to be expressed as a Python script.

Firstly, make sure the file contains the following import clause:

from eosfactory.eosf import *

Secondly, make sure the file defines a string constant named PROJECT_DIR equal to the absolute path of the foo_project folder, i.e. it contains an expression like this:

PROJECT_DIR = "/path/to/foo_project/"

Note that the PROJECT_DIR constant is needed because it is then used to define a variable that holds a reference to the contract:

c = Contract(host, PROJECT_DIR)

And here is a complete (yet trivial) example of a valid file:

from eosfactory.eosf import *

PROJECT_DIR = "/mnt/c/Workspaces/EOS/foo_project/"

def test():
    master = new_master_account()
    host = new_account(master)
    c = Contract(host, PROJECT_DIR)

    alice = new_account(master)
        "hi", {"user":alice}, 
        permission=(alice, Permission.ACTIVE))

    assert("alice" in DEBUG())


if __name__ == "__main__":

For less trivial examples of test scenarios, please refer to examples listed in this folder.

Run the test script

To run your test script, you simply run the file with your python3 executable:

python3 /path/to/your/test/scripts/

Interact with your contract

If you want to manually interact with your smart-contract via EOSFactory, first run the Python CLI:


Inside the Python CLI initialize a local testnet, create a reference to your smart-contract, then build it, and finally deploy it:

from eosfactory.eosf import *
create_account("host", master)
c = Contract(host, "/path/to/foo_project/")

At this stage you are ready to interact with your smart-contract, referring to it either by its hosting account, e.g.

host.push_action("foo", {...})

…or directly by its variable, e.g.

c.push_action("foo", {...})

To stop the local testnet run:


And to exit the Python CLI:


Alternatively, use the ctrl-D shortcut.