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 thefoo_project
folder (it can also be located in a subfolder inside thefoo_project
folder). - If your project requires a C++ header file, it's contained in a file named
foo_header.hpp
, located anywhere inside thefoo_project
folder (it can also be located in a subfolder inside thefoo_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 thefoo_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.
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.
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
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.