@ensdomains/ens-test-env

ens-test-env

How it works

The testing environment used here is implemented in the stateless and stateful tests for ENS app. The environment consists of two parts: the ganache Ethereum node, and the docker graph instance. Which environment type you use is dependent on your testing circumstances.

Configuration

There should be a file named ens-test-env.config.js in your project's root directory. You can add a JSDoc type import to import the config type.

/**
 * @type {import('@ensdomains/ens-test-env').ENSTestEnvConfig}
 **/
module.exports = {
  deployCommand: 'yarn hardhat deploy',
  tenderly: {
    user: 'ens',
    project: 'core',
    key: 'tenderly-key',
  },
  archive: {
    subgraphId: 'QmXxAE7Urtv6TPa8o8XmPwLVQNbH6r35hRKHP63udTxTNa',
    epochTime: 1646894980,
    blockNumber: 12066620,
    baseUrl: 'https://storage.googleapis.com/ens-manager-build-data',
    network: 'mainnet',
  },
  docker: {
    file: './docker-compose.yml',
    sudo: false,
  },
  ethereum: {
    chain: {
      chainId: 0,
    },
    fork: {
      url: 'https://example.com',
    },
    wallet: {
      mnemonic: 'test test test test test test test test test test test junk',
      unlockedAccounts: ['0x0000000000000000000000000000000000000000'],
    },
    database: {
      dbPath: './ganache',
    },
  },
  graph: {
    bypassLocal: false,
  },
  scripts: [
    {
      command: 'example',
      name: 'example',
      prefixColor: 'blue.bold',
      cwd: path.resolve('./'),
      finishOnExit: true,
      waitForGraph: true,
    },
  ],
  paths: {
    archives: './archives',
    data: './data',
  },
}

Environment Types

Stateless

For most testing situations you can use the default settings, which will create a fresh mainnet fork from a specified block as well as deploying a fresh subgraph with the same specified block as it's start block.

Tests should ideally be designed to be stateless where possible, which entails not using hardcoded addresses and not relying on any specific blockchain/graph state. This allows for a much higher test reliability and low maintenance.

Stateful

Some tests may require a specific existing state, for example if a test relies on an old deployment of a contract which can no longer be accurately replicated from a fresh mainnet fork. The stateful environment uses pre-existing subgraph data at a specified block to allow full state access prior to the mainnet fork.

The stateful environment can also be used to more closely replicate a production environment for true full end-to-end tests. You may also want to use this environment for testing with your own personal wallet without using mainnet.

The downside of using the stateful environment is that a test can potentially become unreliable if one of it's dependencies changes. Alongside reliability, running a stateful test most of the time will require access to a specific private key. Given this, you should try to avoid writing stateful tests wherever possible.

Contract deployments

Contract deployments are a small but necessary part of testing, you can deploy contracts to both stateless and stateful environments. After the locally tested contract is deployed, the deployment script should be left in the repo to serve as an archive.

Updating the graph-node dataset

Generally, you will want to set a graft variable in the subgraph.yaml file for the subgraph. You can find more about the ENS subgraph here. You'll also documentation for grafting available here.

To update the graph-node dataset, the BLOCK_HEIGHT variable must be changed within the .env file. It should be set to the same value as the graft block.

If the dataset is a dependency for a local test, you will need to first let your local graph-node dataset update so that your test can pass.

Once your data is up to date, you can run

yarn ens-test-env data --compress

in this directory, which will give you a archive file for your dataset.

Dataset naming scheme

const file = `data_${BLOCK_HEIGHT}_${SUBGRAPH_ID}_${EPOCH_TIME}_${NETWORK}.archive`
// e.g. data_14119046_QmTmU4syjQb8gfNq8TCQGv441qp2zQMNKnQ4smjKhpLQ6F_1643850493_ropsten.archive.tar.lz4

Running the environment

After this you can run:

# Start
yarn ens-test-env start
# Load data only
yarn ens-test-env data --load
# Export generated data
yarn ens-test-env data --compress