Docs
⌘ K

26 minutos

Estrutura de Testes de Unidades

Learn how to use Matchstick, a unit testing framework developed by LimeChain⁠. Matchstick enables Subgraph developers to test their mapping logic in a sandboxed environment and successfully deploy their Subgraphs.

Vantagens de Usar o Matchstick

  • É escrito em Rust e otimizado para o melhor desempenho possível.
  • It gives you access to developer features, including the ability to mock contract calls, make assertions about the store state, monitor Subgraph failures, check test performance, and many more.

Como Começar

Como Instalar Dependências

Para usar os métodos de test helper e executar os testes, instale as seguintes dependências:

yarn add --dev matchstick-as

Como Instalar o PostgreSQL

O graph-node depende do PostgreSQL, então se ainda não o tem, será necessário instalá-lo.

Observação: É altamente recomendável usar os comandos abaixo para evitar erros inesperados.

Usando o MacOS

Comando de instalação:

brew install postgresql

Crie um symlink ao último libpq.5.lib Talvez precise criar este diretório primeiro: /usr/local/opt/postgresql/lib/

ln -sf /usr/local/opt/postgresql@14/lib/postgresql@14/libpq.5.dylib /usr/local/opt/postgresql/lib/libpq.5.dylib

Usando o Linux

Comando de instalação do Postgres (depende da sua distro):

sudo apt install postgresql

Usando o WSL (Subsistema do Windows para o Linux)

Pode usar o Matchstick no WSL tanto com a abordagem do Docker quanto com a abordagem binária. Como o WSL pode ser um pouco complicado, aqui estão algumas dicas caso encontre problemas

static BYTES = Symbol("Bytes") SyntaxError: Unexpected token =

ou

<PROJECT_PATH>/node_modules/gluegun/build/index.js:13 throw up;

Verifique se está em uma versão mais recente do Node.js. O graph-cli não apoia mais a v10.19.0, que ainda é a versão padrão para novas imagens de Ubuntu no WSL. Por exemplo, se o Matchstick é confirmado como funcional no WSL com a v18.1.0, pode trocar para essa versão através do nvm ou ao atualizar o seu Node.js global. Não se esqueça de apagar o node_modules e executar o npm install novamente após atualizar o seu nodejs! Depois, garanta que tem o libpq instalado. Isto pode ser feito ao executar:

sudo apt-get install libpq-dev

E finalmente, não use o graph test (que usa a sua instalação global da graph-cli, e por alguma razão, parece não funcionar no WSL no momento). Em vez disto, use o yarn test ou o npm run test (que usará a instância local do graph-cli; esta funciona muito bem). Para isto, obviamente você precisa de um script "test" no seu arquivo package.json, que pode ser algo simples como

{  "name": "demo-subgraph",  "version": "0.1.0",  "scripts": {    "test": "graph test",    ...  },  "dependencies": {    "@graphprotocol/graph-cli": "^0.56.0",    "@graphprotocol/graph-ts": "^0.31.0",    "matchstick-as": "^0.6.0"  }}

Usando o Matchstick

To use Matchstick in your Subgraph project just open up a terminal, navigate to the root folder of your project and simply run graph test [options] <datasource> - it downloads the latest Matchstick binary and runs the specified test or all tests in a test folder (or all existing tests if no datasource flag is specified).

Opções de CLI

Isto executará todos os testes na pasta-teste:

graph test

Isto executará um teste chamado gravity.test.ts e/ou todos os testes dentro de uma pasta chamada gravity:

graph test gravity

Isto só executará esse arquivo de teste específico:

graph test path/to/file.test.ts

Opções:

-c, --coverage                Run the tests in coverage mode-d, --docker                  Run the tests in a docker container (Note: Please execute from the root folder of the Subgraph)-f, --force                   Binary: Redownloads the binary. Docker: Redownloads the Dockerfile and rebuilds the docker image.-h, --help                    Show usage information-l, --logs                    Logs to the console information about the OS, CPU model and download url (debugging purposes)-r, --recompile               Forces tests to be recompiled-v, --version <tag>           Choose the version of the rust binary that you want to be downloaded/used

Docker

Desde o graph-cli 0.25.2, o comando graph test apoia a execução do matchstick em um container docker com a flag -d. A implementação do docker utiliza o bind mount⁠ para que não precise reconstruir a imagem do docker toda vez que o comando graph test -d for executado. Alternativamente, siga as instruções do repositório do matchstick⁠ para executar o docker manualmente.

❗ graph test -d força o docker run a ser executado com o flag -t. Isto deve ser removido para rodar em ambientes não interativos (como o GitHub CI).

❗ Caso já tenha executado o graph test anteriormente, o seguinte erro pode aparecer durante a compilação do docker:

error from sender: failed to xattr node_modules/binary-install-raw/bin/binary-<platform>: permission denied

Neste caso, crie um .dockerignore na pasta raiz e adicione node_modules/binary-install-raw/bin

Configuração

O Matchstick pode ser configurado para usar um caminho personalizado de tests, libs e manifest através do arquivo de configuração matchstick.yaml:

testsFolder: path/to/testslibsFolder: path/to/libsmanifestPath: path/to/subgraph.yaml

Demo Subgraph

Você pode experimentar com os exemplos deste guia clonando o repositório de Subgraph Demonstrativo⁠

Tutoriais de vídeo

Also you can check out the video series on “How to use Matchstick to write unit tests for your Subgraphs”⁠

Estrutura de testes

IMPORTANT: The test structure described below depends on matchstick-as version >=0.5.0

describe()

describe(name: String , () = {}) — Define um grupo de teste.

Observações:

  • Describes (descrições) não são obrigatórias. O test() ainda pode ser usado da maneira antiga, fora dos blocos describe()

Exemplo:

import { describe, test } from "matchstick-as/assembly/index"import { handleNewGravatar } from "../../src/gravity"describe("handleNewGravatar()", () => {  test("Isto deve criar uma nova entidade Gravatar", () => {    ...  })})

Exemplo aninhado de describe():

import { describe, test } from "matchstick-as/assembly/index"import { handleUpdatedGravatar } from "../../src/gravity"describe("handleUpdatedGravatar()", () => {  describe("Quando houver uma entidade", () => {    test("entidade atualizada", () => {      ...    })  })  describe("Quando não houver uma entidade", () => {    test("nova entidade criada", () => {      ...    })  })})

test()

test(name: String, () =, should_fail: bool) — Define um caso de teste. O test() pode ser usado em blocos describe() ou de maneira independente.

Exemplo:

import { describe, test } from "matchstick-as/assembly/index"import { handleNewGravatar } from "../../src/gravity"describe("handleNewGravatar()", () => {  test("Isto deve criar uma nova Entidade", () => {    ...  })})

ou

test("handleNewGravatar() deve criar uma nova entidade", () => {  ...})

beforeAll()

Executa um bloco de código antes de quaisquer dos testes no arquivo. Se o beforeAll for declarado dentro de um bloco describe, ele é executado no começo daquele bloco describe.

Exemplos:

O código dentro do beforeAll será executado uma vez antes de todos os testes no arquivo.

import { describe, test, beforeAll } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"import { Gravatar } from "../../generated/schema"beforeAll(() => {  let gravatar = new Gravatar("0x0")  gravatar.displayName = “First Gravatar”  gravatar.save()  ...})describe("Quando a entidade não existe", () => {  test("ela deve criar um novo Gravatar com a id 0x1", () => {    ...  })})describe("Quando a entidade já existe", () => {  test("ela deve atualizar o Gravatar com a id 0x0", () => {    ...  })})

O código antes do beforeAll será executado uma vez antes de todos os testes no primeiro bloco describe

mport { describe, test, beforeAll } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"import { Gravatar } from "../../generated/schema"describe("handleUpdatedGravatar()", () => {  beforeAll(() => {    let gravatar = new Gravatar("0x0")    gravatar.displayName = “Primeiro Gravatar”    gravatar.save()    ...  })  test("atualiza Gravatar com id 0x0", () => {    ...  })  test("cria novo Gravatar com id 0x1", () => {    ...  })})

afterAll()

Executa um bloco de código depois de todos os testes no arquivo. Se o afterAll for declarado dentro de um bloco describe, ele será executado no final desse bloco describe.

Exemplo:

O código dentro do afterAll será executado uma vez depois de todos os testes no arquivo.

import { describe, test, afterAll } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"import { store } from "@graphprotocol/graph-ts"afterAll(() => {  store.remove("Gravatar", "0x0")  ...})describe("handleNewGravatar, () => {  test("cria Gravatar com id 0x0", () => {    ...  })})describe("handleUpdatedGravatar", () => {  test("atualiza Gravatar com id 0x0", () => {    ...  })})

O código dentro do afterAll será executado uma vez depois de todos os testes no primeiro bloco describe

import { describe, test, afterAll, clearStore } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"describe("handleNewGravatar", () => {	afterAll(() => {    store.remove("Gravatar", "0x1")    ...	})  test("Cria uma nova entidade com Id 0x0", () => {    ...  })  test("Cria uma nova entidade com Id 0x1", () => {    ...  })})describe("handleUpdatedGravatar", () => {  test("atualiza Gravatar com id 0x0", () => {    ...  })})

beforeEach()

Executa um bloco de código antes de cada teste no arquivo. Se o beforeEach for declarado dentro de um bloco describe, ele será executado antes de cada teste nesse bloco describe.

Exemplos: O código dentro do beforeEach será executado antes de cada teste.

import { describe, test, beforeEach, clearStore } from "matchstick-as/assembly/index"import { handleNewGravatars } from "./utils"beforeEach(() => {  clearStore() // <-- limpa o armazenamento antes de cada teste no arquivo})describe("handleNewGravatars, () => {  test("Teste que exige armazenamento limpo", () => {    ...  })  test("Segundo que exige armazenamento limpo", () => {    ...  })}) ...

O código antes do beforeEach será executado antes de cada teste no describe

import { describe, test, beforeEach } from 'matchstick-as/assembly/index'import { handleUpdatedGravatar, handleNewGravatar } from '../../src/gravity'describe('handleUpdatedGravatars', () => {  beforeEach(() => {    let gravatar = new Gravatar('0x0')    gravatar.displayName = 'Primeiro Gravatar'    gravatar.imageUrl = ''    gravatar.save()  })  test('Atualiza o displayName', () => {    assert.fieldEquals('Gravatar', '0x0', 'displayName', 'Primeiro Gravatar')    // código que deve atualizar o displayName para 1o. Gravatar    assert.fieldEquals('Gravatar', '0x0', 'displayName', '1o. Gravatar')    store.remove('Gravatar', '0x0')  })  test('Atualiza o imageUrl', () => {    assert.fieldEquals('Gravatar', '0x0', 'imageUrl', '')    // código que deve mudar imageUrl para https://www.gravatar.com/avatar/0x0    assert.fieldEquals('Gravatar', '0x0', 'imageUrl', 'https://www.gravatar.com/avatar/0x0')    store.remove('Gravatar', '0x0')  })})

afterEach()

Executa um bloco de código depois de cada teste no arquivo. Se o afterEach for declarado dentro de um bloco describe, será executado após cada teste nesse describe.

Exemplos:

O código dentro do afterEach será executado após cada teste.

import { describe, test, beforeEach, afterEach } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"beforeEach(() => {  let gravatar = new Gravatar("0x0")  gravatar.displayName = “Primeiro Gravatar”  gravatar.save()})afterEach(() => {  store.remove("Gravatar", "0x0")})describe("handleNewGravatar", () => {  ...})describe("handleUpdatedGravatar", () => {  test("Atualiza o displayName", () => {     assert.fieldEquals("Gravatar", "0x0", "displayName", "Primeiro Gravatar")    // código que deve mudar o displayName para 1o. Gravatar    assert.fieldEquals("Gravatar", "0x0", "displayName", "1o. Gravatar")  })  test("Atualiza o imageUrl", () => {    assert.fieldEquals("Gravatar", "0x0", "imageUrl", "")    // código que deve mudar o imageUrl para https://www.gravatar.com/avatar/0x0    assert.fieldEquals("Gravatar", "0x0", "imageUrl", "https://www.gravatar.com/avatar/0x0")  })})

O código dentro do afterEach será executado após cada teste nesse describe

import { describe, test, beforeEach, afterEach } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"describe("handleNewGravatar", () => {  ...})describe("handleUpdatedGravatar", () => {  beforeEach(() => {    let gravatar = new Gravatar("0x0")    gravatar.displayName = "Primeiro Gravatar"    gravatar.imageUrl = ""    gravatar.save()  })  afterEach(() => {    store.remove("Gravatar", "0x0")  })  test("Updates the displayName", () => {     assert.fieldEquals("Gravatar", "0x0", "displayName", "Primeiro Gravatar")    // código que deve atualizar o displayName para 1o. Gravatar    assert.fieldEquals("Gravatar", "0x0", "displayName", "1o. Gravatar")  })  test("Updates the imageUrl", () => {    assert.fieldEquals("Gravatar", "0x0", "imageUrl", "")    // código que deve mudar o imageUrl para https://www.gravatar.com/avatar/0x0    assert.fieldEquals("Gravatar", "0x0", "imageUrl", "https://www.gravatar.com/avatar/0x0")  })})

Asserts

fieldEquals(entityType: string, id: string, fieldName: string, expectedVal: string)equals(expected: ethereum.Value, actual: ethereum.Value)notInStore(entityType: string, id: string)addressEquals(address1: Address, address2: Address)bytesEquals(bytes1: Bytes, bytes2: Bytes)i32Equals(number1: i32, number2: i32)bigIntEquals(bigInt1: BigInt, bigInt2: BigInt)booleanEquals(bool1: boolean, bool2: boolean)stringEquals(string1: string, string2: string)arrayEquals(array1: Array<ethereum.Value>, array2: Array<ethereum.Value>)tupleEquals(tuple1: ethereum.Tuple, tuple2: ethereum.Tuple)assertTrue(value: boolean)assertNull<T>(value: T)assertNotNull<T>(value: T)entityCount(entityType: string, expectedCount: i32)

A partir da versão 0.6.0, asserts também apoiam mensagens de erro personalizadas

assert.fieldEquals('Gravatar', '0x123', 'id', '0x123', 'Id deve ser 0x123')assert.equals(ethereum.Value.fromI32(1), ethereum.Value.fromI32(1), 'Valor deve ser igual a 1')assert.notInStore('Gravatar', '0x124', 'Gravatar não deve estar armazenado')assert.addressEquals(Address.zero(), Address.zero(), 'Address deve ser zero')assert.bytesEquals(Bytes.fromUTF8('0x123'), Bytes.fromUTF8('0x123'), 'Bytes devem ser iguais')assert.i32Equals(2, 2, 'I32 deve ser igual a 2')assert.bigIntEquals(BigInt.fromI32(1), BigInt.fromI32(1), 'BigInt deve ser igual 1')assert.booleanEquals(true, true, 'Boolean deve ser true')assert.stringEquals('1', '1', 'String deve ser igual a 1')assert.arrayEquals([ethereum.Value.fromI32(1)], [ethereum.Value.fromI32(1)], 'Arranjos devem ser iguais')assert.tupleEquals(  changetype<ethereum.Tuple>([ethereum.Value.fromI32(1)]),  changetype<ethereum.Tuple>([ethereum.Value.fromI32(1)]),  'Tuplas devem ser iguais',)assert.assertTrue(true, 'Deve ser true')assert.assertNull(null, 'Deve ser null')assert.assertNotNull('not null', 'Deve não ser null')assert.entityCount('Gravatar', 1, 'Deve haver 2 Gravatars')assert.dataSourceCount('GraphTokenLockWallet', 1, 'Template GraphTokenLockWallet template deve ter uma fonte de dados')assert.dataSourceExists(  'GraphTokenLockWallet',  Address.zero().toHexString(),  'GraphTokenLockWallet deve ter uma fonte de dados para address zero',)

Como Escrever um Teste de Unidade

Vamos ver como seria um simples teste unitário usando os exemplos de Gravatar no Subgraph de Demonstração⁠.

Suponhamos que temos a seguinte função de handler (com duas funções de helper para facilitar):

export function handleNewGravatar(event: NewGravatar): void {  let gravatar = new Gravatar(event.params.id.toHex())  gravatar.owner = event.params.owner  gravatar.displayName = event.params.displayName  gravatar.imageUrl = event.params.imageUrl  gravatar.save()}export function handleNewGravatars(events: NewGravatar[]): void {  events.forEach((event) => {    handleNewGravatar(event)  })}export function createNewGravatarEvent(  id: i32,  ownerAddress: string,  displayName: string,  imageUrl: string,): NewGravatar {  let mockEvent = newMockEvent()  let newGravatarEvent = new NewGravatar(    mockEvent.address,    mockEvent.logIndex,    mockEvent.transactionLogIndex,    mockEvent.logType,    mockEvent.block,    mockEvent.transaction,    mockEvent.parameters,  )  newGravatarEvent.parameters = new Array()  let idParam = new ethereum.EventParam('id', ethereum.Value.fromI32(id))  let addressParam = new ethereum.EventParam(    'ownerAddress',    ethereum.Value.fromAddress(Address.fromString(ownerAddress)),  )  let displayNameParam = new ethereum.EventParam('displayName', ethereum.Value.fromString(displayName))  let imageUrlParam = new ethereum.EventParam('imageUrl', ethereum.Value.fromString(imageUrl))  newGravatarEvent.parameters.push(idParam)  newGravatarEvent.parameters.push(addressParam)  newGravatarEvent.parameters.push(displayNameParam)  newGravatarEvent.parameters.push(imageUrlParam)  return newGravatarEvent}

Primeiro, devemos criar um arquivo de teste no nosso projeto. Este é um exemplo de como ele pode ficar:

import { clearStore, test, assert } from 'matchstick-as/assembly/index'import { Gravatar } from '../../generated/schema'import { NewGravatar } from '../../generated/Gravity/Gravity'import { createNewGravatarEvent, handleNewGravatars } from '../mappings/gravity'test('Can call mappings with custom events', () => {  // Criar uma entidade de teste e guarda no armazenamento como estado inicial (opcional)  let gravatar = new Gravatar('gravatarId0')  gravatar.save()  // Criar eventos simulados  let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac')  let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac')  // Chamar funções de mapeamento passando os eventos que acabamos de criar  handleNewGravatars([newGravatarEvent, anotherGravatarEvent])  // Assertar o estado do armazenamento  assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0')  assert.fieldEquals('Gravatar', '12345', 'owner', '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7')  assert.fieldEquals('Gravatar', '3546', 'displayName', 'cap')  // Limpar o armazenamento para começar o próximo teste do zero  clearStore()})test('Next test', () => {  //...})

Quanta coisa! Primeiro, note que estamos a importar coisas do matchstick-as, a nossa biblioteca de helper do AssemblyScript (distribuída como um módulo npm). O repositório está aqui⁠. O matchstick-as nos dá alguns métodos de teste úteis e define a função test(), que usaremos para construir os nossos blocos de teste. O resto é bem simples — veja o que acontece:

  • Configuramos nosso estado inicial e adicionamos uma entidade de Gravatar personalizada;
  • Definimos dois eventos NewGravatar com os seus dados, usando a função createNewGravatarEvent();
  • Chamamos métodos de handlers para estes eventos — handleNewGravatars() — e passamos a lista dos nossos eventos personalizados;
  • Garantimos o estado da loja. Como isto funciona? — Passamos uma combinação do tipo e da id da Entidade. Depois conferimos um campo específico naquela Entidade e garantimos que ela tem o valor que esperamos que tenha. Estamos a fazer isto tanto para a Entidade Gravatar inicial adicionada ao armazenamento, quanto para as duas entidades Gravatar adicionadas ao chamar a função de handler;
  • E por último — limpamos o armazenamento com clearStore(), para que o nosso próximo teste comece com um objeto de armazenamento novo em folha. Podemos definir quantos blocos de teste quisermos.

Prontinho — criamos o nosso primeiro teste! 👏

Now in order to run our tests you simply need to run the following in your Subgraph root folder:

graph test Gravity

E se tudo der certo, deve receber a seguinte resposta:

Matchstick diz "Todos os testes passados!”

Cenários de teste comuns

Como hidratar o armazenamento com um certo estado

Os utilizadores podem hidratar o armazenamento com um conjunto conhecido de entidades. Aqui está um exemplo para inicializar o armazenamento com uma entidade Gravatar:

let gravatar = new Gravatar('entryId')gravatar.save()

Como chamar uma função de mapeamento com um evento

Um utilizador pode criar um evento personalizado e passá-lo a uma função de mapeamento ligada ao armazenamento:

import { store } from 'matchstick-as/assembly/store'import { NewGravatar } from '../../generated/Gravity/Gravity'import { handleNewGravatars, createNewGravatarEvent } from './mapping'let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac')handleNewGravatar(newGravatarEvent)

Como chamar todos os mapeamentos com fixações de eventos

Os utilizadores podem chamar os mapeamentos com fixações de teste.

import { NewGravatar } from '../../generated/Gravity/Gravity'import { store } from 'matchstick-as/assembly/store'import { handleNewGravatars, createNewGravatarEvent } from './mapping'let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac')let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac')handleNewGravatars([newGravatarEvent, anotherGravatarEvent])
export function handleNewGravatars(events: NewGravatar[]): void {    events.forEach(event => {        handleNewGravatar(event);    });}

Como simular chamadas de contratos

Os utilizadores podem simular chamadas de contratos:

import { addMetadata, assert, createMockedFunction, clearStore, test } from 'matchstick-as/assembly/index'import { Gravity } from '../../generated/Gravity/Gravity'import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts'let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7')let expectedResult = Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947')let bigIntParam = BigInt.fromString('1234')createMockedFunction(contractAddress, 'gravatarToOwner', 'gravatarToOwner(uint256):(address)')  .withArgs([ethereum.Value.fromSignedBigInt(bigIntParam)])  .returns([ethereum.Value.fromAddress(Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947'))])let gravity = Gravity.bind(contractAddress)let result = gravity.gravatarToOwner(bigIntParam)assert.equals(ethereum.Value.fromAddress(expectedResult), ethereum.Value.fromAddress(result))

Como demonstrado, para simular uma chamada de contrato e conseguir um valor de retorno de linha-dura, o utilizador deve fornecer um endereço de contrato, nome de função, assinatura de função, arranjo de argumentos — e claro, o valor de retorno.

Os utilizadores também podem simular regressos de funções:

let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7')createMockedFunction(contractAddress, 'getGravatar', 'getGravatar(address):(string,string)')  .withArgs([ethereum.Value.fromAddress(contractAddress)])  .reverts()

Como simular arquivos IPFS (do matchstick 0.4.1)

Os utilizadores podem simular arquivos IPFS com a função mockIpfsFile(hash, filePath). A função aceita dois argumentos: o primeiro é o hash/caminho do arquivo IPFS, e o segundo é o caminho a um arquivo local.

NOTE: When testing ipfs.map/ipfs.mapJSON, the callback function must be exported from the test file in order for matchstick to detect it, like the processGravatar() function in the test example bellow:

Arquivo test.ts:

import { assert, test, mockIpfsFile } from 'matchstick-as/assembly/index'import { ipfs } from '@graphprotocol/graph-ts'import { gravatarFromIpfs } from './utils'// Export ipfs.map() callback in order for matchstick to detect itexport { processGravatar } from './utils'test('ipfs.cat', () => {  mockIpfsFile('ipfsCatfileHash', 'tests/ipfs/cat.json')  assert.entityCount(GRAVATAR_ENTITY_TYPE, 0)  gravatarFromIpfs()  assert.entityCount(GRAVATAR_ENTITY_TYPE, 1)  assert.fieldEquals(GRAVATAR_ENTITY_TYPE, '1', 'imageUrl', 'https://i.ytimg.com/vi/MELP46s8Cic/maxresdefault.jpg')  clearStore()})test('ipfs.map', () => {  mockIpfsFile('ipfsMapfileHash', 'tests/ipfs/map.json')  assert.entityCount(GRAVATAR_ENTITY_TYPE, 0)  ipfs.map('ipfsMapfileHash', 'processGravatar', Value.fromString('Gravatar'), ['json'])  assert.entityCount(GRAVATAR_ENTITY_TYPE, 3)  assert.fieldEquals(GRAVATAR_ENTITY_TYPE, '1', 'displayName', 'Gravatar1')  assert.fieldEquals(GRAVATAR_ENTITY_TYPE, '2', 'displayName', 'Gravatar2')  assert.fieldEquals(GRAVATAR_ENTITY_TYPE, '3', 'displayName', 'Gravatar3')})

Arquivo utils.ts:

import { Address, ethereum, JSONValue, Value, ipfs, json, Bytes } from "@graphprotocol/graph-ts"import { Gravatar } from "../../generated/schema"...// callback do ipfs.mapexport function processGravatar(value: JSONValue, userData: Value): void {  // See the JSONValue documentation for details on dealing  // with JSON values  let obj = value.toObject()  let id = obj.get('id')  if (!id) {    return  }  // Callbacks também podem criar entidades  let gravatar = new Gravatar(id.toString())  gravatar.displayName = userData.toString() + id.toString()  gravatar.save()}// função que chama o ipfs.catexport function gravatarFromIpfs(): void {  let rawData = ipfs.cat("ipfsCatfileHash")  if (!rawData) {    return  }  let jsonData = json.fromBytes(rawData as Bytes).toObject()  let id = jsonData.get('id')  let url = jsonData.get("imageUrl")  if (!id || !url) {    return  }  let gravatar = new Gravatar(id.toString())  gravatar.imageUrl = url.toString()  gravatar.save()}

Como afirmar o estado do armazenamento

Os utilizadores podem afirmar o estado final (ou parcial) do armazenamento através de entidades de afirmação. Para isto, o utilizador precisa fornecer um tipo de Entidade, a ID específica de uma Entidade, o nome de um campo naquela Entidade, e o valor esperado do campo. Aqui vai um exemplo rápido:

import { assert } from 'matchstick-as/assembly/index'import { Gravatar } from '../generated/schema'let gravatar = new Gravatar('gravatarId0')gravatar.save()assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0')

A função assert.fieldEquals() conferirá a igualdade do campo dado contra o valor dado esperado. O teste acabará em erro, com mensagem correspondente, caso os valores NÃO sejam iguais. Caso contrário, o teste terá êxito.

Como interagir com metadados de Eventos

Os utilizadores podem usar metadados-padrão de transações, que podem ser retornados como um ethereum.Event com a função newMockEvent(). O seguinte exemplo mostra como podes ler/escrever a estes campos no objeto de Evento:

// Leituralet logType = newGravatarEvent.logType// Escritalet UPDATED_ADDRESS = '0xB16081F360e3847006dB660bae1c6d1b2e17eC2A'newGravatarEvent.address = Address.fromString(UPDATED_ADDRESS)

Como afirmar a igualdade das variáveis

assert.equals(ethereum.Value.fromString("hello"); ethereum.Value.fromString("hello"));

Como afirmar que uma Entidade não está no armazenamento

Os utilizadores podem afirmar que uma entidade não existe no armazenamento. A função toma um tipo e uma id de entidade. Caso a entidade esteja, de facto, na loja, o teste acabará em erro, com uma mensagem de erro relevante. Veja um exemplo rápido de como usar esta funcionalidade:

assert.notInStore('Gravatar', '23')

Impressão do armazenamento completo, ou de entidades individuais dele (para debugging)

Pode imprimir o armazenamento inteiro na consola com esta função de helper:

import { logStore } from 'matchstick-as/assembly/store'logStore()

Desde a versão 0.6.0, o logStore não imprime mais campos derivados; em vez disto, os utilizadores podem usar a nova função logEntity. O logEntity pode ser usado para imprimir qualquer entidade, não só as que têm campos derivados. O logEntity pega o tipo e a ID da entidade, e um flag showRelated para indicar se os utilizadores querem imprimir as entidades derivadas relacionadas.

import { logEntity } from 'matchstick-as/assembly/store'logEntity("Gravatar", 23, true)

Falhas esperadas

Os utilizadores podem encontrar falhas esperadas, com o flag shouldFail nas funções test():

test(  'Deve chamar um erro',  () => {    throw new Error()  },  true,)

Caso o teste seja marcado com shouldFail = true mas NÃO falhe, isto será mostrado como um erro nos logs e o bloco de teste não terá êxito. E se for marcado com shouldFail = false (o estado normal), o executor de teste travará.

Logging

Ter logs personalizados nos testes de unidade é a mesma coisa que logar nos mapeamentos. A diferença é que o objeto do log deve ser importado do matchstick-as, em vez do graph-ts. Aqui vai um exemplo simples com todos os tipos de log não-críticos:

import { test } from "matchstick-as/assembly/index";import { log } from "matchstick-as/assembly/log";test("Success", () => {    log.success("Sucesso!". []);});test("Error", () => {    log.error("Erro! :( ", []);});test("Debug", () => {    log.debug("Debug em progresso...", []);});test("Info", () => {    log.info("Informação!", []);});test("Warning", () => {    log.warning("Cuidado!", []);});

Os utilizadores também podem simular uma falha crítica, como no seguinte:

test('Explodir tudo', () = {  log.critical('É boooomba!')})

Logar erros críticos interromperá a execução dos testes e causará um desastre. Afinal, queremos ter certeza que o seu código não tenha logs críticos no lançamento; perceberia imediatamente se isto acontecer.

Como testar campos derivados

Testar campos derivados permite aos utilizadores configurar um campo numa entidade e atualizar outra automaticamente, caso ela derive um dos seus campos da primeira entidade.

Antes da versão 0.6.0, era possível resgatar as entidades derivadas ao acessá-las como propriedades ou campos de entidade, como no seguinte exemplo:

let entity = ExampleEntity.load('id')let derivedEntity = entity.derived_entity

Desde a versão 0.6.0, isto é feito com a função loadRelated do graph-node. As entidades derivadas podem ser acessadas como são nos handlers.

test('Derived fields example test', () => {  let mainAccount = GraphAccount.load('12')!  assert.assertNull(mainAccount.get('nameSignalTransactions'))  assert.assertNull(mainAccount.get('operatorOf'))  let operatedAccount = GraphAccount.load('1')!  operatedAccount.operators = [mainAccount.id]  operatedAccount.save()  mockNameSignalTransaction('1234', mainAccount.id)  mockNameSignalTransaction('2', mainAccount.id)  mainAccount = GraphAccount.load('12')!  assert.assertNull(mainAccount.get('nameSignalTransactions'))  assert.assertNull(mainAccount.get('operatorOf'))  const nameSignalTransactions = mainAccount.nameSignalTransactions.load()  const operatorsOfMainAccount = mainAccount.operatorOf.load()  assert.i32Equals(2, nameSignalTransactions.length)  assert.i32Equals(1, operatorsOfMainAccount.length)  assert.stringEquals('1', operatorsOfMainAccount[0].id)  mockNameSignalTransaction('2345', mainAccount.id)  let nst = NameSignalTransaction.load('1234')!  nst.signer = '11'  nst.save()  store.remove('NameSignalTransaction', '2')  mainAccount = GraphAccount.load('12')!  assert.i32Equals(1, mainAccount.nameSignalTransactions.load().length)})

Teste de loadInBlock

Desde a versão 0.6.0, é possível testar o loadInBlock com o mockInBlockStore, que permite a simulação de entidades no cache de blocos.

import { afterAll, beforeAll, describe, mockInBlockStore, test } from 'matchstick-as'import { Gravatar } from '../../generated/schema'describe('loadInBlock', () => {  beforeAll(() => {    mockInBlockStore('Gravatar', 'gravatarId0', gravatar)  })  afterAll(() => {    clearInBlockStore()  })  test('Pode usar entity.loadInBlock() para retirar a entidade do armazenamento do cache no bloco atual', () => {    let retrievedGravatar = Gravatar.loadInBlock('gravatarId0')    assert.stringEquals('gravatarId0', retrievedGravatar!.get('id')!.toString())  })  test('Retorna null ao chamar entity.loadInBlock() se uma entidade não existir no bloco atual', () => {    let retrievedGravatar = Gravatar.loadInBlock('IDoNotExist')    assert.assertNull(retrievedGravatar)  })})

Como testar fontes de dados dinâmicas

É possível testar fontes de dados dinâmicas ao simular o valor de retorno das funções context(), address() e network() do namespace do dataSource. Estas funções atualmente retornam o seguinte: context() — retorna uma entidade vazia (DataSourceContext); address() — retorna 0x0000000000000000000000000000000000000000; network() — retorna mainnet. As funções create(...) e createWithContext(...) são simuladas para não terem uso, para que não precisem ser chamadas nos testes. Dá para mudar os valores de retorno através das funções do namespace dataSourceMock no matchstick-as (versão 0.3.0+).

Exemplo abaixo:

Primeiro temos o seguinte handler de eventos (que foi apropriado intencionalmente para demonstrar a falsificação de fontes de dados):

export function handleApproveTokenDestinations(event: ApproveTokenDestinations): void {  let tokenLockWallet = TokenLockWallet.load(dataSource.address().toHexString())!  if (dataSource.network() == 'rinkeby') {    tokenLockWallet.tokenDestinationsApproved = true  }  let context = dataSource.context()  if (context.get('contextVal')!.toI32() > 0) {    tokenLockWallet.setBigInt('tokensReleased', BigInt.fromI32(context.get('contextVal')!.toI32()))  }  tokenLockWallet.save()}

E então, temos o teste que usa um dos métodos do namespace dataSourceMock para determinar um novo valor de retorno para todas as funções do dataSource:

import { assert, test, newMockEvent, dataSourceMock } from 'matchstick-as/assembly/index'import { BigInt, DataSourceContext, Value } from '@graphprotocol/graph-ts'import { handleApproveTokenDestinations } from '../../src/token-lock-wallet'import { ApproveTokenDestinations } from '../../generated/templates/GraphTokenLockWallet/GraphTokenLockWallet'import { TokenLockWallet } from '../../generated/schema'test('Exemplo simples de simulação de fonte de dados', () => {  let addressString = '0xA16081F360e3847006dB660bae1c6d1b2e17eC2A'  let address = Address.fromString(addressString)  let wallet = new TokenLockWallet(address.toHexString())  wallet.save()  let context = new DataSourceContext()  context.set('contextVal', Value.fromI32(325))  dataSourceMock.setReturnValues(addressString, 'rinkeby', context)  let event = changetype<ApproveTokenDestinations>(newMockEvent())  assert.assertTrue(!wallet.tokenDestinationsApproved)  handleApproveTokenDestinations(event)  wallet = TokenLockWallet.load(address.toHexString())!  assert.assertTrue(wallet.tokenDestinationsApproved)  assert.bigIntEquals(wallet.tokensReleased, BigInt.fromI32(325))  dataSourceMock.resetValues()})

Note que o dataSourceMock.resetValues() é chamado no final. Isto é porque os valores são lembrados quando mudados, e devem ser reconfigurados caso queira voltar aos valores padrão.

Teste de criação de fontes de dados dinâmicas

Desde a versão 0.6.0, é possível testar se uma nova fonte de dados foi criada de um modelo. Esta função apoia modelos ethereum/contract e file/ipfs. Há quatro funçôes para isto:

  • assert.dataSourceCount(templateName, expectedCount) pode ser usado para impor a contagem esperada de fontes de dados do modelo especificado
  • assert.dataSourceExists(templateName, address/ipfsHash) impõe que foi criada uma fonte de dados com o identificador especificado (seja um endereço de contrato ou um hash de arquivo IPFS) de um modelo especificado
  • logDataSources(templateName) imprime todas as fontes de dados do modelo especificado ao console, para propósitos de debug
  • readFile(path) lê um arquivo JSON que representa um arquivo IPFS e retorna o conteúdo como Bytes

Teste de modelos ethereum/contract

test('ethereum/contract dataSource creation example', () => {  // Impor que não há dataSources criadas de modelo GraphTokenLockWallet  assert.dataSourceCount('GraphTokenLockWallet', 0)  // Criar uma nova datasource GraphTokenLockWallet com o endereço 0xA16081F360e3847006dB660bae1c6d1b2e17eC2A  GraphTokenLockWallet.create(Address.fromString('0xA16081F360e3847006dB660bae1c6d1b2e17eC2A'))  // Assegurar que foi criada a dataSource  assert.dataSourceCount('GraphTokenLockWallet', 1)  // Adicionar uma segunda dataSource com contexto  let context = new DataSourceContext()  context.set('contextVal', Value.fromI32(325))  GraphTokenLockWallet.createWithContext(Address.fromString('0xA16081F360e3847006dB660bae1c6d1b2e17eC2B'), context)  // Assertar que agora há 2 dataSources  assert.dataSourceCount('GraphTokenLockWallet', 2)  // Impor que foi criada uma dataSource com o endereço "0xA16081F360e3847006dB660bae1c6d1b2e17eC2B"  // Lembrar que o tipo `Address` transforma para caixa baixa quando decodificado, então o endereço deve ser passado como caixa-baixa ao determinar se existe  assert.dataSourceExists('GraphTokenLockWallet', '0xA16081F360e3847006dB660bae1c6d1b2e17eC2B'.toLowerCase())  logDataSources('GraphTokenLockWallet')})
Exemplo de resultado de logDataSource
🛠  {  "0xa16081f360e3847006db660bae1c6d1b2e17ec2a": {    "kind": "ethereum/contract",    "name": "GraphTokenLockWallet",    "address": "0xa16081f360e3847006db660bae1c6d1b2e17ec2a",    "context": null  },  "0xa16081f360e3847006db660bae1c6d1b2e17ec2b": {    "kind": "ethereum/contract",    "name": "GraphTokenLockWallet",    "address": "0xa16081f360e3847006db660bae1c6d1b2e17ec2b",    "context": {      "contextVal": {        "type": "Int",        "data": 325      }    }  }}

Teste de modelos file/ipfs

Assim como as fontes dinâmicas de dados de contrato, os utilizadores podem testar fontes de dados de arquivos e os seus handlers

Exemplo de subgraph.yaml
...templates: - kind: file/ipfs    name: GraphTokenLockMetadata    network: mainnet    mapping:      kind: ethereum/events      apiVersion: 0.0.9      language: wasm/assemblyscript      file: ./src/token-lock-wallet.ts      handler: handleMetadata      entities:        - TokenLockMetadata      abis:        - name: GraphTokenLockWallet          file: ./abis/GraphTokenLockWallet.json
Exemplo de schema.graphql
"""Token Lock Wallets que têm GRT trancado"""type TokenLockMetadata @entity {  "Endereço da token lock wallet"  id: ID!  "Começo da agenda de lançamento"  startTime: BigInt!  "Final da agenda de lançamento"  endTime: BigInt!  "Número de períodos entre o início e o fim"  periods: BigInt!  "Hora quando os lançamentos começam"  releaseStartTime: BigInt!}
Exemplo de metadata.json
{  "startTime": 1,  "endTime": 1,  "periods": 1,  "releaseStartTime": 1}
Exemplo de handler
export function handleMetadata(content: Bytes): void {  // dataSource.stringParams() retorna CID de Fonte de Dados de Arquivo  // stringParam() será simulado no teste de handler  // para saber mais https://thegraph.com/docs/en/developing/creating-a-subgraph/#create-a-new-handler-to-process-files  let tokenMetadata = new TokenLockMetadata(dataSource.stringParam())  const value = json.fromBytes(content).toObject()  if (value) {    const startTime = value.get('startTime')    const endTime = value.get('endTime')    const periods = value.get('periods')    const releaseStartTime = value.get('releaseStartTime')    if (startTime && endTime && periods && releaseStartTime) {      tokenMetadata.startTime = startTime.toBigInt()      tokenMetadata.endTime = endTime.toBigInt()      tokenMetadata.periods = periods.toBigInt()      tokenMetadata.releaseStartTime = releaseStartTime.toBigInt()    }    tokenMetadata.save()  }}
Exxemplo de teste
import { assert, test, dataSourceMock, readFile } from 'matchstick-as'import { Address, BigInt, Bytes, DataSourceContext, ipfs, json, store, Value } from '@graphprotocol/graph-ts'import { handleMetadata } from '../../src/token-lock-wallet'import { TokenLockMetadata } from '../../generated/schema'import { GraphTokenLockMetadata } from '../../generated/templates'test('file/ipfs dataSource creation example', () => {  // Gerar CID da dataSource do arquivo de local ipfsHash + ipfs  // Por exemplo QmaXzZhcYnsisuue5WRdQDH6FDvqkLQX1NckLqBYeYYEfm/example.json  const ipfshash = 'QmaXzZhcYnsisuue5WRdQDH6FDvqkLQX1NckLqBYeYYEfm'  const CID = `${ipfshash}/example.json`  // Criar uma nova dataSource com o CID gerado  GraphTokenLockMetadata.create(CID)  // Verificar se foi criada a dataSource  assert.dataSourceCount('GraphTokenLockMetadata', 1)  assert.dataSourceExists('GraphTokenLockMetadata', CID)  logDataSources('GraphTokenLockMetadata')  // Agora temos que simular os metadados da dataSource, e especificamente dataSource.stringParam()  // dataSource.stringParams usa o valor de dataSource.address(), então vamos simular o endereçocom dataSourceMock de matchstick-as  // Primeiro, vamos reiniciar os valores e usar dataSourceMock.setAddress() para configurar o CID  dataSourceMock.resetValues()  dataSourceMock.setAddress(CID)  // Agora precisamos gerar os Bytes para passar para o handler da dataSource  // Para este caso, apresentamos uma nova função readFile, que lê um json local e retorna o conteúdo como Bytes  const content = readFile(`path/to/metadata.json`)  handleMetadata(content)  // Agora vamos testar se foi criado um TokenLockMetadata  const metadata = TokenLockMetadata.load(CID)  assert.bigIntEquals(metadata!.endTime, BigInt.fromI32(1))  assert.bigIntEquals(metadata!.periods, BigInt.fromI32(1))  assert.bigIntEquals(metadata!.releaseStartTime, BigInt.fromI32(1))  assert.bigIntEquals(metadata!.startTime, BigInt.fromI32(1))})

Cobertura de Testes

Using Matchstick, Subgraph developers are able to run a script that will calculate the test coverage of the written unit tests.

A ferramenta de cobertura de testes pega os binários de teste wasm compilados e os converte a arquivos wat, que podem então ser facilmente vistoriados para ver se os handlers definidos em subgraph.yaml foram chamados ou não. Como a cobertura de código (e os testes em geral) está num estado primitivo no AssemblyScript e WebAssembly, o Matchstick não pode procurar por coberturas de branch. Em vez disto, supomos que, se um handler foi chamado, o evento/a função correspondente já foi simulado com êxito.

Pré-requisitos

Para executar a funcionalidade da cobertura de teste fornecida no Matchstick, prepare algumas coisas com antecedência:

Exportar seus handlers

Para que o Matchstick confira quais handlers serão executados, estes handlers devem ser exportados do arquivo de teste primeiro. No nosso exemplo, temos o seguinte handler a ser importado no nosso arquivo gravity.test.ts:

import { handleNewGravatar } from '../../src/gravity'

Para que essa função seja visível (para ser incluída no arquivo wat por nome), também precisamos exportá-la assim:

export { handleNewGravatar }

Uso

Assim que tudo estiver pronto, para executar a ferramenta de cobertura de testes, basta:

graph test -- -c

Um comando coverage personalizado também pode ser adicionado ao seu arquivo package.json, assim:

"scripts": {    /.../    "coverage": "graph test -- -c"  },

Isto executará a ferramenta de cobertura. Verás algo parecido com isto no terminal:

$ graph test -cSkipping download/install step because binary already exists at /Users/petko/work/demo-subgraph/node_modules/binary-install-raw/bin/0.4.0___  ___      _       _         _   _      _|  \/  |     | |     | |       | | (_)    | || .  . | __ _| |_ ___| |__  ___| |_ _  ___| | __| |\/| |/ _` | __/ __| '_ \/ __| __| |/ __| |/ /| |  | | (_| | || (__| | | \__ \ |_| | (__|   <\_|  |_/\__,_|\__\___|_| |_|___/\__|_|\___|_|\_\Compiling...Running in coverage report mode. ️Reading generated test modules... 🔎️Generating coverage report 📝Handlers for source 'Gravity':Handler 'handleNewGravatar' is tested.Handler 'handleUpdatedGravatar' is not tested.Handler 'handleCreateGravatar' is tested.Test coverage: 66.7% (2/3 handlers).Handlers for source 'GraphTokenLockWallet':Handler 'handleTokensReleased' is not tested.Handler 'handleTokensWithdrawn' is not tested.Handler 'handleTokensRevoked' is not tested.Handler 'handleManagerUpdated' is not tested.Handler 'handleApproveTokenDestinations' is not tested.Handler 'handleRevokeTokenDestinations' is not tested.Test coverage: 0.0% (0/6 handlers).Global test coverage: 22.2% (2/9 handlers).

Duração do teste na saída do log

A saída do log inclui a duração do teste. Veja um exemplo:

[Quinta, 31 Mar 2022 13:54:54 +0300] Programa executado em: 42.270ms.

Erros comuns do compilador

Critical: Could not create WasmInstance from valid module with context: unknown import: wasi_snapshot_preview1::fd_write has not been defined

Isso significa que você usou console.log no seu código, que não é apoiado pelo AssemblyScript. Por favor, considere usar a API de registo

ERROR TS2554: Expected ? arguments, but got ?.

return new ethereum.Block(defaultAddressBytes, defaultAddressBytes, defaultAddressBytes, defaultAddress, defaultAddressBytes, defaultAddressBytes, defaultAddressBytes, defaultBigInt, defaultBigInt, defaultBigInt, defaultBigInt, defaultBigInt, defaultBigInt, defaultBigInt, defaultBigInt);

 in ~lib/matchstick-as/assembly/defaults.ts(18,12) ERROR TS2554: Expected ? arguments, but got ?.

return new ethereum.Transaction(defaultAddressBytes, defaultBigInt, defaultAddress, defaultAddress, defaultBigInt, defaultBigInt, defaultBigInt, defaultAddressBytes, defaultBigInt);

 in ~lib/matchstick-as/assembly/defaults.ts(24,12)

A diferença nos argumentos é causada pela diferença no graph-ts e no matchstick-as. Problemas como este são melhor resolvidos ao atualizar tudo para a versão mais recente.

Outros Recursos

For any additional support, check out this demo Subgraph repo using Matchstick⁠.

Feedback

Caso tenha qualquer pergunta, opinião, pedidos de recursos, ou só quer entrar em contacto, venha para o Discord do The Graph — lá, temos um canal dedicado ao Matchstick, chamado 🔥| unit-testing.