Project repo for running end to end system tests against a variety of networks, with Ten being the primary network under test. Other networks supported include Ganache, Arbitrum and Sepolia. The repo uses the pysys test framework to manage all tests and their execution. All tests are fully system level using web3.py to interact with the networks which are managed outside the scope of the tests (with the exception of ganache which can be started locally). Note the project is currently under active development and further information on running the tests will be added to this readme over time.
The top level structure of the project is as below;
├── README.md # Readme
├── .github # Github configuration including workflows
├── .default.properties # Default properties file detailing connection and keys required for running
├── pysysproject.xml # The pysys project file detailing configuration options
├── get_artifacts.sh # Build script to build artifacts from go-ten required for running Ten protocol tests
├── admin # Used for administering the Ten testnet
├── artifacts # Directory to store artifacts for running Ten tests
├── src # The source root for all test code
│ ├── javascript # A library of javascript client tooling
│ ├── python # The python source root for pysys extensions
│ └── solidity # A library of smart contracts
├── tests # The test root for all tests
│ ├── generic # Network agnostic tests
│ └── ten # Ten specific tests
└── utils # The project utils root for utilities used by the tests
├── docker # Docker build and run files
├── github # Azure VM github self hosted running build files
├── release # Utilitiy scripts for making a new release of go-ten
└── testnet # Utilities for building and interacting with a local testnet
The .default.properties file contains properties for running the tests that are common to any
user. User specific properties should be added into a ~/.tentest/user.properties file. Properties will first be
looked for in the ~/.tentest/user.properties should it exist, and if not will fall back to the default properties.
Should you wish to run the tests locally on your host machine against a local testnet, the easiest approach is to use
the docker image for the e2e tests. Prior to running, a local testnet should be built and run as described in the section
Building and running a local testnet
of the go-ten repository README.md file. Once the local testnet is running, the e2e docker image can be pulled down from
the Azure container registry and run from the root of the ten-test repository using the below;
./utils/docker/run_image.sh --version=<version>where version should be latest if the latest build from main is required, or otherwise the released version of
go-ten and ten-test e.g. 0.19 , 0.18 etc. Note that this represents the head of the relevant releases
branch and therefore will be the latest patch release of that major.minor version.
As stated earlier, running the tests requires the ten-test repository to be cloned in the same parent directory
as go-ten, and the dependent artifacts to be built (these are the wallet extension, and the ABIs for the bridge
contracts). To build the artifacts run ./get_artifacts.sh in the root of the ten-test checkout. To install all
dependencies for running the tests use the following on OSX or Linux accordingly;
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew update
brew upgrade
brew remove node --force
brew install node@18
brew link --overwrite node@18
brew tap ethereum/ethereum
brew install ethereum
brew install solidity
brew install python
brew install gnuplot
npm install solc@0.8.15 --global
npm install console-stamp@3.1.2 --global
npm install ganache@7.9.1 --global
npm install ganache-cli@6.12.2 --global
npm install web3@1.9.0 --global
npm install ethers@5.7.2 --global
npm install ethers6@npm:ethers@6.13.1 --global
npm install commander@11.1.0 --global
npm install @openzeppelin/merkle-tree@1.0.6 --global
pip3 install web3==6.13.0
pip3 install pysys==1.6.1
pip3 install solc-select==1.0.4
pip3 install py-solc-x==2.0.2
pip3 install numpy==1.26.4
solc-select install 0.8.15
solc-select use 0.8.15apt update
DEBIAN_FRONTEND=noninteractive apt-get install -y tzdata
apt-get install -y software-properties-common
add-apt-repository ppa:ethereum/ethereum
apt update
apt install -y curl
apt install -y solc
apt install -y gnuplot
apt install -y ethereum
curl -sL https://deb.nodesource.com/setup_18.x | bash -
apt-get install -y nodejs
npm install console-stamp --global
npm install ganache --global
npm install ganache-cli --global
npm install web3@1.9.0 --global
npm install ethers@5.7.2 --global
npm install ethers6@npm:ethers@6.13.1 --global
npm install commander@11.1.0 --global
npm install @openzeppelin/merkle-tree@1.0.6 --global
apt install -y python3-pip
python3 -m pip install web3==5.31.3
python3 -m pip install pysys==1.6.1
python3 -m pip install solc-select
python3 -m pip install py-solc-x
python3 -m pip install numpy==1.24.4Once installed it should be possible to run all tests from the pysys.py cli as described in the following sections. Note
that depending on differences in your installation, and should you want to add in your own accounts on Sepolia or Arbitrum,
you may need to override the .default.properties file by creating a user specific properties file in
~/.tentest/user.properties. Common overrides will include the path to various binaries used when running the tests,
and account details. An example of an override properties file is as given below where binary locations and the project ID
for Sepolia and Arbitrum are set as overrides, along with real accounts as set up within metamask;
[binaries.darwin]
solc = /opt/homebrew/bin/solc
ganache = /opt/homebrew/bin/ganache-cli
node = /opt/homebrew/bin/node
node_path = /opt/homebrew/lib/node_modules
[env.all]
Account1PK=<private key of account 1 available e.g. via metamask>
Account2PK=<private key of account 2>
Account3PK=<private key of account 3>
Account4PK=<private key of account 4>
[env.sepolia]
ProjectID = <id>
[env.arbitrum.sepolia]
APIKey = <api key>
Each test is a separate directory within ten-test/tests where the directory name denotes the testcase id. Each
test will contain a run.py file (the execution and validation steps) and a pysystest.xml file (metadata about the
test such as its title, purpose, supported modes it can be run in). Note that the tests can be run against a variety
of networks using the -m mode option. The E2E tests have specifically been designed such that any generic tests
can be run against Ten, Ganache, Arbitrum or Sepolia. To print out information on the tests, or to run them
against a particular network, change directory to ten-test/tests and run as below;
# print out test titles
pysys.py print
# print out full test details
pysys.py print -f
# run the tests against Ten sepolia-testnet
pysys.py run -m ten.sepolia
# run the tests against Ten uat-testnet
pysys.py run -m ten.uat
# run the tests against Ten dev-testnet
pysys.py run -m ten.dev
# run the tests against Ten local testnet
pysys.py run -m ten.local
# run the tests against Ten sim testnet
pysys.py run -m ten.sim
# run the tests against a local ganache network
pysys.py run -m ganache
# run the tests against the Arbitrum network
pysys.py run -m arbitrum.sepolia
# run the tests against the Sepolia network
pysys.py run -m sepoliaNote that should you wish to run against a Ten local testnet, you will need to build and run the local testnet
yourself using the approach as described in the go-ten readme.
Both the local testnet and the faucet will need to be started. To run against ganache the test framework will start the
local ganache network on your behalf, and tear it down when test execution is complete. To run the same tests against
Sepolia or Arbitrum, the ~/.tentest/user.properties should be created as described earlier.
If you wish to run against a Ten simulated testnet, you will need to run the simulation from within the go-land IDE, and
additionally start the faucet manually. To run the network, in the IDE run the method TestRunLocalNetwork within the
file integration/networktest/tests/helpful/spin_up_local_network_test.go. In order for the network to come up, you
need to set the IDE flag in the Run Configurations to true, or remove the line networktest.TestOnlyRunsInIDE(t) from
within the method. To run the faucet, in go-ten directory execute the below;
go run ./tools/faucet/cmd --nodePort 17801 -nodeHost 127.0.0.1 --pk 0x8dfb8083da6275ae3e4f41e3e8a8c19d028d32c9247e24530933782f2a05035b --jwtSecret This_is_the_secret --serverPort 99
The pysys launch cli provides a rich interface to allow you to run a
specific test, ranges of tests, or groups of tests, as well as running them in different modes, with different
verbosity logging, and in cycles. See the cli documentation for more detail using pysys.py run -h. When running tests
pysys will search the directory tree for all tests available from the current working directory downwards, and then
filter based on the user request e.g.
# run a specific test
pysys.py run -m ten.sepolia gen_cor_001
# run a range of tests (using python list slicing syntax)
pysys.py run -m ten.sepolia gen_cor_001:gen_cor_004
pysys.py run -m ten.sepolia gen_cor_003:
# run a test multiple times
pysys.py run -m ten.sepolia -c 5 gen_cor_003
# run a test with full verbosity logging
pysys.py run -m ten.sepolia -v DEBUG gen_cor_003