{"id":18437848,"url":"https://github.com/zilliqa/evm_js_tests","last_synced_at":"2025-04-14T13:14:26.026Z","repository":{"id":181042106,"uuid":"648414252","full_name":"Zilliqa/evm_js_tests","owner":"Zilliqa","description":null,"archived":false,"fork":false,"pushed_at":"2024-01-18T10:41:37.000Z","size":1984,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-02-16T10:42:59.848Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Zilliqa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-01T23:22:53.000Z","updated_at":"2023-10-02T05:43:10.000Z","dependencies_parsed_at":"2024-12-24T23:32:45.386Z","dependency_job_id":null,"html_url":"https://github.com/Zilliqa/evm_js_tests","commit_stats":null,"previous_names":["zilliqa/evm_js_tests"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zilliqa%2Fevm_js_tests","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zilliqa%2Fevm_js_tests/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zilliqa%2Fevm_js_tests/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zilliqa%2Fevm_js_tests/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Zilliqa","download_url":"https://codeload.github.com/Zilliqa/evm_js_tests/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248886341,"owners_count":21177645,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T06:16:25.388Z","updated_at":"2025-04-14T13:14:25.999Z","avatar_url":"https://github.com/Zilliqa.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quick Start\n\n```bash\n    npm install\n    npx hardhat test    # to run tests\n    npx hardhat test --network devnet    # to run tests against the devnet\n    npx hardhat test --log-jsonrpc    # to run tests and print JSON-RPC requests/responses\n    npx hardhat test --log-txnid    # to run tests and print transaction ids.\n    DEBUG=true npx hardhat test    # to run tests and print log messages. `.env` file can be used as well.\n    npx hardhat test --grep something    # to run tests containing `something` in the description\n    npx hardhat test filename    # to run tests of `filename`\n    npx hardhat test folder/*    # to run tests of `folder`\n    npx hardhat test --parallel   # to run tests in parallel\n    npx hardhat test test/scilla/*    # to run scilla tests only\n    SCILLA=false npx hardhat test   # to disable scilla tests. `.env` file can be used as well.\n```\n\n# Start Testing\n\n## A few simple rules before start\n\n1. Please prefer ethers.js library to web3.js. Our default library to use throughout the the code is **ethers.js**.\n2. Please use [typescript](./Typescript.md). Javascript is not used anymore in this test suite. You can learn more about typescript [here](./Typescript.md).\n3. Please don't add commented tests. You can't add disabled tests as well, unless you create a ticket for it.\n\nFor more info, see [Testing conventions and best practices](#testing-conventions-and-best-practices).\n\n## Add a new contract\n\n1. Add a new contract to `contracts` folder\n2. Compile it using `npx hardhat compile`\n\n## Add a new test scenario\n\n1. Add a new javascript file to `test` folder\n2. Deploy the contract.\n3. Add your test cases using `describe` and `it` blocks\n4. Expect results using [chai assertions](https://www.chaijs.com/api/bdd/). Below is the list of most useful ones:\n\n```javascript\nexpect(123).to.equal(123);\nexpect(2).to.not.equal(1);\nexpect(true).to.be.true;\nexpect(false).to.be.false;\nexpect(null).to.be.null;\nexpect(undefined).to.be.undefined;\nexpect(contract.address).exist;\nexpect(\"foobar\").to.have.string(\"bar\");\nexpect(badFn).to.throw();\n```\n\nIt's also useful to use [hardhat chai matchers](https://hardhat.org/hardhat-chai-matchers/docs/overview) if possible:\n\n```javascript\nawait expect(contract.call()).to.emit(contract, \"Uint\").withArgs(3); // For events\nawait expect(contract.call()).to.be.reverted;\nawait expect(contract.call()).to.be.revertedWith(\"Some revert message\");\nexpect(\"0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266\").to.be.a.properAddress;\nawait expect(contract.withdraw())\n  .to.changeEtherBalance(contract.address, ethers.utils.parseEther(\"-1.0\"))\n  .to.changeEtherBalance(owner.address, ethers.utils.parseEther(\"1.0\"));\n```\n\n## Run the tests\n\n```bash\nnpx hardhat test        # Run all the tests\nnpx hardhat test --grep \"something\"     # Run tests containing \"something\" in their descriptions\nnpx hardhat test --bail     # Stop running tests after the first test failure\nnpx hardhat test --parallel\n```\n\n## Run the tests with ethernal plugin\n\n```bash\nETHERNAL_EMAIL=\"devops+ethernal@zilliqa.com\" ETHERNAL_PASSWORD=\"YourPassword\" ETHERNAL_WORKSPACE=\"Zilliqa Testnet\" npx hardhat test --network public_testnet\n```\n\nEthernal is an [EVM-based blockchain explorer](https://tryethernal.com)\n\nFor more info, see [hardhat ethernal plugin](https://github.com/tryethernal/hardhat-ethernal)\n\n# How to define a new network for hardhat\n\n1. Add a new network to `hardhat.config.ts` inside `networks` property:\n\n```javascript\n...\nconst config: any = {\n  solidity: \"0.8.9\",\n  defaultNetwork: \"isolated_server\",\n  networks: {\n    ganache: {\n      url: \"http://127.0.0.1:7545\",\n      chainId: 1337,\n      accounts: [\n        \"c95690aed4461afd835b17492ff889af72267a8bdf7d781e305576cd8f7eb182\",\n        \"05751249685e856287c2b2b9346e70a70e1d750bc69a35cef740f409ad0264ad\"\n      ]\n    },\n...\n```\n\n2. Change the default network:\n\n```javascript\nmodule.exports = {\n  solidity: \"0.8.9\",\n  defaultNetwork: \"ganache\",\n...\n```\n\nAlternatively, It's possible to run the tests with `--network` option:\n\n```bash\nnpx hardhat test --network ganache\n```\n\n# How to debug\n\n- Use `--log-txnid` to print out the transaction IDs.\n- Use `--log-jsonrpc` option to enable Json-RPC requests/responses logging. It only works with ethers.js currently.\n- Use vscode debugger\n- Use `logDebug` and `DEBUG=true` environment variable to print out log messages.\n\n```bash\nDEBUG=true npx hardhat test\n```\n\nAlternatively you can change `DEBUG` variable in the `.env` file.\n\n# Testing conventions and best practices\n\n- File names tries to tell us the scenario we're testing.\n- We don't pollute test results with logs. So if you want to add them for debugging, please consider using `logDebug` function:\n\n```typescript\nimport {logDebug} from \"../helpers\";\nlogDebug(result);\n```\n\n- Every `it` block should have one assertion, readable and easy to understand.\n- Follow `GIVEN`, `WHEN` and, `THEN` BDD style\n  - Top level `describe` for `GIVEN`\n  - Nested `describe`s for `WHEN`\n  - `it` blocks for `THEN`\n\n```javascript\n// GIVEN\ndescribe(\"Contract with payable constructor\", function () {\n  // WHEN\n  describe(\"When ethers.js is used\", function () {\n    let contract;\n    let INITIAL_BALANCE = 10;\n\n    before(async function () {\n      const Contract = await ethers.getContractFactory(\"WithPayableConstructor\");\n      contract = await Contract.deploy({\n        value: INITIAL_BALANCE\n      });\n    });\n\n    // THEN\n    it(\"Should be deployed successfully\", async function () {\n      expect(contract.address).exist;\n    });\n  });\n});\n```\n\n- It's acceptable to disable tests as long as the following rules are fulfilled:\n  1. A useless test should be removed from code, not disabled.\n  2. A disabled test should be in `xit` instead of `it` block. `xit` blocks are for skipping tests. Commented tests are FORBIDDEN.\n  3. A disabled test should have a `FIXME` comment containing an issue number to track it. Disabled tests must be addressed ASAP.\n\n```javascript\n    // FIXME: In ZIL-4879\n    xit(\"Should not be possible to move more than available tokens to some address\", async function () {\n```\n\n- We use `[@tag1, @tag2, @tag3, ...]` in test descriptions to add tags to tests. This is based on [Mocha's tagging convention](https://github.com/mochajs/mocha/wiki/Tagging). In order to run `tag1` tests, you can use `--grep @tag1`.\n\n```javascript\nit(\"Should return correct value for string [@transactional, @ethers_js]\", async function () {\n  await contract.setName(STRING);\n  expect(await contract.getStringPublic()).to.be.eq(STRING);\n});\n```\n\n- `@transactional` tag is used for those tests which generate ethereum transactions. Calling pure functions or view functions doesn't generate a transaction for example. Transactional tests may use for populating an empty testnet with some transactions.\n\n- Second parameter to `expect` function is used to log in the case of test failure. We use it to debug failing tests on devnet or testnet easier.\n\n```javascript\nconst txn = await payer.sendTransaction({\n  to: payee.address,\n  value: FUND\n});\n\nexpect(await ethers.provider.getBalance(payee.address), `Txn Hash: ${txn.hash}`).to.be.eq(FUND);\n```\n\n# Scilla\n\n## Testing\n\nScilla testing is done through the [hardhat scilla plugin](https://www.npmjs.com/package/hardhat-scilla-plugin). It's possible to deploy a scilla contract by its name and call its transitions just like a normal function call. It's also possible to get a field value through a function call. In the below sections, all of these topics are covered in detail.\n\n### Deploy a contract\n\nTo deploy a contract all you need to know is its name:\n\n```typescript\nimport {parallelizer} from \"../../helpers\";\n\nlet contract: ScillaContract = await parallelizer.deployScillaContract(\"SetGet\");\nlet contract: ScillaContract = await parallelizer.deployScillaContract(\"HelloWorld\", \"Hello World\"); // Contract with initial parameters.\n```\n\n### Call a transition\n\nIt's not harder than calling a normal function in typescript.\nLet's assume we have a transition named `Set` which accepts a `number` as its parameter. Here is how to call it:\n\n```typescript\nawait contract.Set(12);\n```\n\n### Get field value\n\nIf a given contract has a filed named `msg` is possible to get its current value using a function call to `msg()`\n\n```typescript\nconst msg = await contract.msg();\n```\n\n### Expect a result\n\nChai matchers can be used to expect a value:\n\n```typescript\nit(\"Should set state correctly\", async function () {\n  const VALUE = 12;\n  await contract.Set(VALUE);\n  expect(await contract.value()).to.be.eq(VALUE);\n});\n```\n\nThere are two custom chai matchers specially developed to `expect` scilla events. `eventLog` and `eventLogWithParams`.\nUse `eventLog` if you just need to expect event name:\n\n```typescript\nit(\"Should contain event data if emit function is called\", async function () {\n  const tx = await contract.emit();\n  expect(tx).to.have.eventLog(\"Emit\");\n});\n```\n\nOtherwise, if you need to deeply expect an event, you should use `eventLogWithParams`. The first parameter is again the event name. The rest are parameters of the expected event. If you expect to have an event like `getHello` sending a parameter named `msg` with a `\"hello world\"` value:\n\n```typescript\nit(\"Should send getHello() event when getHello() transition is called\", async function () {\n  const tx = await contract.getHello();\n  expect(tx).to.have.eventLogWithParams(\"getHello()\", {value: \"hello world\", vname: \"msg\"});\n});\n```\n\nYou can even expect data type of the parameter(s):\n\n```typescript\nexpect(tx).to.have.eventLogWithParams(\"getHello()\", {value: \"hello world\", vname: \"msg\", type: \"String\"});\n```\n\nType should be a valid Scilla type.\n\nBut if you just want to expect on the value of a event parameter do this:\n\n```typescript\nexpect(tx).to.have.eventLogWithParams(\"getHello()\", {value: \"hello world\"});\n```\n\nfor more tests please take look at [scilla tests](./test/scilla/).\n\n### TODO\n\n- Support formatting complex data types such as `Map` and `List`.\n\n## Tasks\n\n### Scilla checker task\n\nTo run `scilla-checker` on all of the scilla contracts in the [contracts directory](./contracts/) run:\n\n```bash\nnpx hardhat scilla-check --libdir path_to_stdlib\n```\n\nalternatively, you can check a specific file(s):\n\n```bash\nnpx hardhat scilla-check --libdir path_to_stdlib contracts/scilla/helloWorld.scilla\n```\n\n### TODO\n\n- Add `scilla-fmt` task\n\n# miscellaneous\n\n## .env File\n\nto change some of the testing behaviors environment variables are used. They can be changed using the `.env` file. Here is the list of them:\n\n- `DEBUG=true` to enable debugging logs.\n- `SCILLA=false` to ignore scilla tests.\n- `MOCHA_TIMEOUT=3000` to set the mocha timeout in milliseconds.\n- `ETHERNAL_EMAIL=\"devops+ethernal@zilliqa.com\"` to set Ethernal email.\n- `ETHERNAL_WORKSPACE=\"Zilliqa Testnet\"` to set Ethernal workspace.\n- `ETHERNAL_PASSWORD=\"Your Password\"` If it's not set, ethernal plugin will be disabled.\n\n## Scripts\n\nTo get the balances of the current accounts, run:\n\n```bash\nnpx hardhat run scripts/Accounts.js\nnpx hardhat run scripts/Accounts.js --network public_testnet\n```\n\nWhen you start a testnet, your funds are initially in zil addresses, which is inconvenient.\nThe following script takes the private keys you have in your hardhat config,\nand moves half of the funds at that address to the same address, but eth style.\n\n```bash\nnpx hardhat run scripts/FundAccountsFromZil.ts --network testnet\n```\n\n## Setup github pre-commit hook\n\nYou may want to set up pre-commit hook to fix your code before commit by:\n`npm run prepare`\n\nAlternatively, you can always fix your code manually before uploading to remote:\n\n`npm run lint`\n\n## Feed devnet with transactions\n\nIt's possible to use [FeedDevnet.js](scripts/FeedDevnet.js) to send transactions to devnet continuously:\n\n```bash\nnpx hardhat run scripts/FeedDevnet.js --network devnet\n```\n\nInstead of `devnet` we can pass any other networks defined in the [config file](hardhat.config.js).\n\n## Increase tests timeout\n\nSet the timeout as a environment variable before running the tests. It's in milliseconds.\n\n```bash\nMOCHA_TIMEOUT=300000 npx hardhat test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzilliqa%2Fevm_js_tests","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzilliqa%2Fevm_js_tests","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzilliqa%2Fevm_js_tests/lists"}