_section: Testing

Testing is a critical part of any library which wishes to remain secure, safe
and reliable.

Ethers currently has **over 23k tests** among its test suites, which are all
made available for other projects to use as simple exported GZIP-JSON files.

The tests are run on every check-in and the results can been seen on the
[GitHub CI Action](link-github-ci).

We also strive to constantly add new test cases, especially when issues
arise to ensure the issue is present prior to the fix, corrected after the
fix and included to prevent future changes from causing a regression.

A large number of the test cases were created procedurally by using
known correct implementations from various sources (such as Geth) and
written in different languages and verified with multiple libraries.

For example, the ABI test suites were generated by procedurally generating
a list of types, for each type choosing a random (valid) value, which then
was converted into a Solidity source file, compiled using ``solc`` and
deployed to a running Parity node and executed, with its outputs being
captured. Similar to the how many of the hashing, event and selector test
cases were created.


_subsection: Supported Platforms @<testing-supported>

While web technologies move quite fast, especially in the Web3 universe, we try
to keep ethers as accessible as possible.

Currently ethers should work on almost any ES3 or better environment and tests
are run against:

- node.js 8.x
- node.js 10.x
- node.js 12.x
- node.js 13.x
- Web Browsers (using UMD)
- Web Browsers (using ES modules)

If there is an environment you feel has been overlooked or have suggestions, please feel
free to reach out by opening an [issue on Github](link-github-issues).

We would like to add a test build for Expo and React as those developers often seem
to encounter pain points when using ethers, so if you have experience or ideas on this,
[bug us](link-github-issues).

The next Major version (probably summer 2021) will likely drop support for node 8.x
and will require ES2015 for [Proxy](link-js-proxy).

Certain features in JavaScript are also avoided, such as look-behind tokens in regular
expressions, since these have caused conflicts (at import time) with certain JavaScript
environments such as [Otto](link-otto).

Basically, the moral of the story is "be inclusive and don't drop people needlessly".


_subsection: Test Suites @<testing-suites>

The test suites are available as gzipped JSON files in the
``@ethersproject/testcases``, which makes it easy to install and import
(both GZIP and JSON are quite easy to consume from most languages). Each
test suite also has its schema available in this package.

_table: Test Suites @style<full>

$Account:            Private Keys and addresses in checksum and ICAP formats
$ContractEvents:     Compiled Solidity, ABI interfaces, input types/values with the
                     output types/values for emitted events; all tests were
                     executed against real Ethereum nodes
$ContractAbi:        Compiled Solidity, ABI interfaces, input types/values with the
                     output types/values, encoded and decoded binary data and normalized
                     values for function calls executed against real Ethereum nodes.
$ContractAbi2:       Identical to ``contract-interface``, except with emphasis on
                     the ABIv2 coder which supports nested dynami types and structured
                     data
$ContractSignatures: Contract signatures and matching selectors
$Hashes:             Data and respective hashes against a variety of hash functions
$HDNode:             HDNodes (BIP-32) with mnemonics, entropy, seed and computed nodes
                     with pathes and addresses
$Namehash:           ENS names along with computed [namehashes](link-namehash
$Nameprep:           IDNA and Nameprep representations including official vectors
$RLP:                Recursive-Length Prefix (RLP) data and encodings
$SoliditiyHashes:    Hashes based on the Solidity non-standard packed form
$Transactions:       Signed and unsigned transactions with their serialized formats
                     including both with and without EIP-155 replay protection
$Units:              Values converted between various units
$Wallet:             Keystore JSON format wallets, passwords and decrypted values
$Wordlist:           Fully decompressed BIP-39 official wordlists

|   **Filename**                   |  **Test Cases**        <|
| accounts.json.gz                 | $Account               <|
| contract-events.json.gz          | $ContractEvents        <|
| contract-interface.json.gz       | $ContractAbi           <|
| contract-interface-abi2.json.gz  | $ContractAbi2          <|
| contract-signatures.json.gz      | $ContractSignatures    <|
| hashes.json.gz                   | $Hashes                <|
| hdnode.json.gz                   | $HDNode                <|
| namehash.json.gz                 | $Namehash              <|
| nameprep.json.gz                 | $Nameprep              <|
| rlp-coder.json.gz                | $RLP                   <|
| solidity-hashes.json.gz          | $SoliditiyHashes       <|
| transactions.json.gz             | $Transactions          <|
| units.json.gz                    | $Units                 <|
| wallets.json.gz                  | $Wallet                <|
| wordlists.json.gz                | $Wordlist              <|


_subsection: Test Suite API @<testing-api>

There are also convenience functions for those developing directly in TypeScript.

_property: testcases.loadTests(tag) => Array<TestCase>
Load all the given testcases for the //tag//.

A tag is the string in the above list of test case names not including
any extension (e.g. ``"solidity-hashes"``)

_property: testcases.TestCase.TEST_NAME
Most testcases have its schema available as a TypeScript type to make testing
each property easier.

_heading: Deterministic Random Numbers (DRNG)

When creating test cases, often we want want random data from the perspective
we do not case what values are used, however we want the values to be consistent
across runs. Otherwise it becomes difficult to reproduce an issue.

In each of the following the seed is used to control the random value returned. Be
sure to tweak the seed properly, for example on each iteration change the value and
in recursive functions, concatenate to the seed.

_property: testcases.randomBytes(seed, lower [, upper ]) => Uint8Array
Return at least //lower// random bytes, up to //upper// (exclusive) if specified,
given //seed//. If //upper// is omitted, exactly ///lower// bytes are returned.

_property: testcases.randomHexString(seed, lower [, upper ]) => string<[[DataHexString]]>
Identical to randomBytes, except returns the value as a [[DataHexString]] instead of a
Uint8Array.

_property: testcases.randomNumber(seed, lower, upper) => number
Returns a random number of at least //lower// and less than //upper//
given //seed//.


_subsection: Schemas @<testing-schemas>

This section is still a work in progress, but will outline some of the more nuanced
aspects of the test cases and their values.

There will likely be an overhaul of the test cases in the next major version, to
make code coverage testing more straight forward and to collapse some of the redundancy.

For example, there is no longer a need to separate the ABI and ABIv2 test case and the
accounts and transactions suites can be merged into one large collection.


_heading: Accounts

Basic account information using a private key and computing various address forms.

Tests were verified against [EthereumJS](https:/\/github.com/ethereumjs) and custom
scripts created to directly interact with Geth and cpp implementations.

//See: ``accounts.json.gz``//

_table: Properties

|   **Property**      |   **Meaning**                             |
|   name              |  The testcase name                        |
|   privateKey        |  The private key                          |
|   address           |  The address (lowercase)                  |
|   checksumAddress   |  The address with checksum-adjusted case  |
|   icapAddress       |  The ICAP address                         |

_code: Example @lang<script>
{
  "name":            "random-1023",
  "address":         "0x53bff74b9af2e3853f758a8d2bd61cd115d27782",
  "privateKey":      "0x8ab0e165c2ea461b01cdd49aec882d179dccdbdb5c85c3f9c94c448aa65c5ace",
  "checksumAddress": "0x53bFf74b9Af2E3853f758A8D2Bd61CD115d27782",
  "icapAddress":     "XE709S6NUSJR6SXQERCMYENAYYOZ2Y91M6A"
}


_heading: Contract Interface

Procedurally generated test cases to test ABI coding.

_code: Example @lang<script>
{
  "name":             "random-1999",
  "source":           "contract Test {\n    function test() constant returns (address, bool, bytes14[1]) {\n        address a = address(0x061C7F399Ee738c97C7b7cD840892B281bf772B5);\n        bool b = bool(true);\n        bytes14[1] memory c;\n        c[0] = bytes14(0x327621c4abe12d4f21804ed40455);\n        return (a, b, c);\n    }\n}\n",
  "types":            "[\"address\",\"bool\",\"bytes14[1]\"]",
  "interface":        "[{\"constant\":true,\"inputs\":[],\"name\":\"test\",\"outputs\":[{\"name\":\"\",\"type\":\"address\"},{\"name\":\"\",\"type\":\"bool\"},{\"name\":\"\",\"type\":\"bytes14[1]\"}],\"type\":\"function\"}]\n",
  "bytecode":         "0x6060604052610175806100126000396000f360606040526000357c010000000000000000000000000000000000000000000000000000000090048063f8a8fd6d1461003957610037565b005b610046600480505061009d565b604051808473ffffffffffffffffffffffffffffffffffffffff1681526020018315158152602001826001602002808383829060006004602084601f0104600f02600301f150905001935050505060405180910390f35b600060006020604051908101604052806001905b60008152602001906001900390816100b157905050600060006020604051908101604052806001905b60008152602001906001900390816100da5790505073061c7f399ee738c97c7b7cd840892b281bf772b59250600191506d327621c4abe12d4f21804ed404557201000000000000000000000000000000000000028160006001811015610002579090602002019071ffffffffffffffffffffffffffffffffffff191690818152602001505082828295509550955061016d565b50505090919256",
  "result":           "0x000000000000000000000000061c7f399ee738c97c7b7cd840892b281bf772b50000000000000000000000000000000000000000000000000000000000000001327621c4abe12d4f21804ed40455000000000000000000000000000000000000",
  "values":           "[{\"type\":\"string\",\"value\":\"0x061C7F399Ee738c97C7b7cD840892B281bf772B5\"},{\"type\":\"boolean\",\"value\":true},[{\"type\":\"buffer\",\"value\":\"0x327621c4abe12d4f21804ed40455\"}]]",
  "normalizedValues": "[{\"type\":\"string\",\"value\":\"0x061C7F399Ee738c97C7b7cD840892B281bf772B5\"},{\"type\":\"boolean\",\"value\":true},[{\"type\":\"buffer\",\"value\":\"0x327621c4abe12d4f21804ed40455\"}]]",
  "runtimeBytecode":  "0x60606040526000357c010000000000000000000000000000000000000000000000000000000090048063f8a8fd6d1461003957610037565b005b610046600480505061009d565b604051808473ffffffffffffffffffffffffffffffffffffffff1681526020018315158152602001826001602002808383829060006004602084601f0104600f02600301f150905001935050505060405180910390f35b600060006020604051908101604052806001905b60008152602001906001900390816100b157905050600060006020604051908101604052806001905b60008152602001906001900390816100da5790505073061c7f399ee738c97c7b7cd840892b281bf772b59250600191506d327621c4abe12d4f21804ed404557201000000000000000000000000000000000000028160006001811015610002579090602002019071ffffffffffffffffffffffffffffffffffff191690818152602001505082828295509550955061016d565b50505090919256"
}


_heading: Contract Signatures

Computed ABI signatures and the selector hash.

_code: Example @lang<script>
{
  "name":      "random-1999",
  "sigHash":   "0xf51e9244",
  "abi":       "[{\"constant\":false,\"inputs\":[{\"name\":\"r0\",\"type\":\"string[2]\"},{\"name\":\"r1\",\"type\":\"uint128\"},{\"components\":[{\"name\":\"a\",\"type\":\"bytes\"},{\"name\":\"b\",\"type\":\"bytes\"},{\"name\":\"c\",\"type\":\"bytes\"}],\"name\":\"r2\",\"type\":\"tuple\"},{\"name\":\"r3\",\"type\":\"bytes\"}],\"name\":\"testSig\",\"outputs\":[],\"payable\":false,\"stateMutability\":\"nonpayable\",\"type\":\"function\"},{\"constant\":true,\"inputs\":[],\"name\":\"test\",\"outputs\":[{\"name\":\"r0\",\"type\":\"string[2]\"},{\"name\":\"r1\",\"type\":\"uint128\"},{\"components\":[{\"name\":\"a\",\"type\":\"bytes\"},{\"name\":\"b\",\"type\":\"bytes\"},{\"name\":\"c\",\"type\":\"bytes\"}],\"name\":\"r2\",\"type\":\"tuple\"},{\"name\":\"r3\",\"type\":\"bytes\"}],\"payable\":false,\"stateMutability\":\"pure\",\"type\":\"function\"}]",
  "signature": "testSig(string[2],uint128,(bytes,bytes,bytes),bytes)"
}

_heading: Hashes

_code: Examples @lang<script>
{
  "data":      "0x3718a88ceb214c1480c32a9d",
  "keccak256": "0x82d7d2dc3d384ddb289f41917b8280675bb1283f4fe2b601ac7c8f0a2c2824fa",
  "sha512":    "0xe93462bb1de62ba3e6a980c3cb0b61728d3f771cea9680b0fa947b6f8fb2198a2690a3a837495c753b57f936401258dfe333a819e85f958b7d786fb9ab2b066c",
  "sha256":    "0xe761d897e667aa72141dd729264c393c4ddda5c62312bbd21b0f4d954eba1a8d"
}


_heading: Hierarchal Deterministic Node (BIP-32)

Tests for [BIP-32](link-bip-32) HD Wallets.

_code: Example @lang<script>
{
  "name":     "trezor-23",
  "entropy":  "0xf585c11aec520db57dd353c69554b21a89b20fb0650966fa0a9d6f74fd989d8f",
  "mnemonic": "void come effort suffer camp survey warrior heavy shoot primary clutch crush open amazing screen patrol group space point ten exist slush involve unfold",
  "locale":   "en",
  "password": "TREZOR",
  "hdnodes": [
    {
      "path":       "m",
      "address":    "0xfd8eb95169ce57eab52fb69bc6922e9b6454d9aa",
      "privateKey": "0x679bf92c04cf16307053cbed33784f3c4266b362bf5f3d7ee13bed6f2719743c"
    },
    {
      "address":    "0xada964e9f10c4fc9787f9e17f00c63fe188722b0",
      "privateKey": "0xdcbcb48a2b11eef0aab93a8f88d83f60a3aaabb34f9ffdbe939b8f059b30f2b7",
      "path":       "m/8'/8'/2/3/4"
    },
    {
      "privateKey": "0x10fd3776145dbeccb3d6925e4fdc0d58b452fce40cb8760b12f8b4223fafdfa6",
      "address":    "0xf3f6b1ef343d5f5f231a2287e801a46add43eb06",
      "path":       "m/1'/3'"
    },
    {
      "address":    "0xb7b0fdb6e0f79f0529e95400903321e8a601b411",
      "privateKey": "0x093a8ff506c95a2b79d397aed59703f6212ff3084731c2f03089b069ae76e69d",
      "path":       "m/8'/4'/7'"
    },
    {
      "path":       "m/7'/5'/11",
      "privateKey": "0x6bd79da4dfa7dd0abf566a011bdb7cba0d28bba9ca249ba25880d5dabf861b42",
      "address":    "0x1b3ad5fa50ae32875748107f4b2160829cc10536"
    },
    {
      "path":       "m/9'/6'/2'/7'/3'",
      "address":    "0x42eb4bed59f3291d02387cf0fb23098c55d82611",
      "privateKey": "0xfc173acba7bc8bb2c434965d9e99f5a221f81add421bae96a891d08d60be11dd"
    }
  ],
  "seed": "0x01f5bced59dec48e362f2c45b5de68b9fd6c92c6634f44d6d40aab69056506f0e35524a518034ddc1192e1dacd32c1ed3eaa3c3b131c88ed8e7e54c49a5d0998"
}


_heading: ENS Namehash

Test cases for the [ENS Namehash Algorithm](link-namehash).

_code: Examples
{
  "expected": "0x33868cc5c3fd3a9cd3adbc1e868ea133d2218f60dc2660c3bc48d8b1f4961384",
  "name":     "ViTalIk.WALlet.Eth",
  "test":     "mixed case"
}


_heading: RLP Coder

_code: Examples @lang<script>
{
  "name":    "arrayWithNullString3",
  "encoded": "0xc3808080",
  "decoded": [ "0x", "0x", "0x" ]
}


_heading: Solidity Hashes

Tests for the non-standard packed form of the Solidity hash functions.

These tests were created by procedurally generating random signatures and
values that match those signatures, constructing the equivalent Soldity,
compiling it and deploying it to a Parity node then evaluating the response.

_code: Example @lang<script>
{
  "name":      "random-1999",
  "keccak256": "0x7d98f1144a0cd689f720aa2f11f0a73bd52a2da1117175bc4bacd93c130966a1",
  "ripemd160": "0x59384617f8a06efd57ab106c9e0c20c3e64137ac000000000000000000000000",
  "sha256":    "0xf9aeea729ff39f8d372d8552bca81eb2a3c5d433dc8f98140040a03b7d81ac92",
  "values": [
    "0xcdffcb5242e6",
    "0xc1e101b60ebe4688",
    "0x5819f0ef5537796e43bdcd48309f717d6f7ccffa",
    "0xec3f3f9f",
    false,
    true
  ],
  "types": [
    "int184",
    "int176",
    "address",
    "int64",
    "bool",
    "bool"
  ]
}


_heading: Transactions

Serialized signed and unsigned transactions with both EIP-155 enabled and
disabled.

_code: Examples @lang<script>
{
  "name":                        "random-998",
  "privateKey":                  "0xd16c8076a15f7fb583f05dc12686fe526bc59d298f1eb7b9a237b458133d1dec",
  "signedTransactionChainId5":   "0xf8708391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc82ea059891894eb180cb7c6c45a52f62d2103420d3ad0bc3ba518d0a25ed910842522a0155c0ea2aee2ea82e75843aab297420bad907d46809d046b13d692928f4d78aa",
  "gasLimit":                    "0x36fcf36da03ee4",
  "to":                          "0x9577303fd4e0acbe72c6c116acab5bf63f0b1e9c",
  "data":                        "0x7dc8",
  "accountAddress":              "0x6d4a6aff30ca5ca4b8422eea0ebcb669c7d79859",
  "unsignedTransaction":         "0xed8391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc8",
  "nonce":                       "0x91d450",
  "gasPrice":                    "0x8517cfba",
  "signedTransaction":           "0xf8708391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc81ba05030832331e6be48c95e1569a1ca9505c495486f72d6009b3a30fadfa05d9686a05cd3116b416d2362da1e9b0ca7fb1856c4e591cc22e63b395bd881ce2d3735e6",
  "unsignedTransactionChainId5": "0xf08391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc8058080",
  "value":                       "0x65fdc7"
}


_heading: Units

Unit conversion.

_code: Example @lang<script>
{
  "name":          "one-two-three-3",
  "gwei_format":   "-1234567890123456.789012345",
  "ether_format":  "-1234567.890123456789012345",
  "gwei":          "-1234567890123456.789012345",
  "ether":         "-1234567.890123456789012345",
  "finney":        "-1234567890.123456789012345",
  "wei":           "-1234567890123456789012345",
  "finney_format": "-1234567890.123456789012345"
}


_heading: Wallets

Tests for the JSON keystore format.

_code: Example @lang<script>
{
  "mnemonic":   null,
  "name":       "secretstorage_password",
  "type":       "secret-storage",
  "password":   "foo",
  "privateKey": "0xf03e581353c794928373fb0893bc731aefc4c4e234e643f3a46998b03cd4d7c5",
  "hasAddress": true,
  "json":       "{\"address\":\"88a5c2d9919e46f883eb62f7b8dd9d0cc45bc290\",\"Crypto\":{\"cipher\":\"aes-128-ctr\",\"ciphertext\":\"10adcc8bcaf49474c6710460e0dc974331f71ee4c7baa7314b4a23d25fd6c406\",\"cipherparams\":{\"iv\":\"1dcdf13e49cea706994ed38804f6d171\"},\"kdf\":\"scrypt\",\"kdfparams\":{\"dklen\":32,\"n\":262144,\"p\":1,\"r\":8,\"salt\":\"bbfa53547e3e3bfcc9786a2cbef8504a5031d82734ecef02153e29daeed658fd\"},\"mac\":\"1cf53b5ae8d75f8c037b453e7c3c61b010225d916768a6b145adf5cf9cb3a703\"},\"id\":\"fb1280c0-d646-4e40-9550-7026b1be504a\",\"version\":3}\n",
  "address":    "0x88a5c2d9919e46f883eb62f7b8dd9d0cc45bc290"
}