06.UsingEOSFactoryWithExistingProject.md

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.

Prerequisites

• 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 foo_test.py. 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 foo_test.py file needs to be expressed as a Python script.

Firstly, make sure the foo_test.py file contains the following import clause:

from eosfactory.eosf import *

Secondly, make sure the foo_test.py 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 foo_test.py file:

from eosfactory.eosf import *

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

def test():
    reset()
    
    master = new_master_account()
    host = new_account(master)
    
    c = Contract(host, PROJECT_DIR)
    c.build()
    c.deploy()

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

    assert("alice" in DEBUG())

    stop()

if __name__ == "__main__":
    test()

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 foo_test.py file with your python3 executable:

python3 /path/to/your/test/scripts/foo_test.py

Interact with your contract

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

python3

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 *
reset()
create_master_account("master")
create_account("host", master)
c = Contract(host, "/path/to/foo_project/")
c.build()
c.deploy()

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:

stop()

And to exit the Python CLI:

exit()

Alternatively, use the ctrl-D shortcut.