You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
👋 Welcome to **Matchstick** - a unit testing framework for The Graph protocol. Try out your mapping logic in a sandboxed environment and ensure your handlers run correctly when deploying your awesome subgraph!
5
+
👋 Welcome to **Matchstick** - a unit testing framework for The Graph protocol. Try out your mapping
6
+
logic in a sandboxed environment and ensure your handlers run correctly when deploying your awesome
7
+
subgraph!
6
8
7
9
## Quick Start 🚀
8
10
9
-
**Matchstick** relies on a helper library - [matchstick-as](https://github.com/LimeChain/matchstick-as"matchstick-as"), written in **AssemblyScript** and used as an import in the unit tests.
11
+
**Matchstick** relies on a helper library -
12
+
[matchstick-as](https://github.com/LimeChain/matchstick-as'matchstick-as'), written in
13
+
**AssemblyScript** and used as an import in the unit tests.
10
14
11
15
### Configuration ⚙️
12
-
Matchstick can be configured to use a custom tests and libs folder via `matchstick.yaml` config file:
16
+
17
+
Matchstick can be configured to use a custom tests and libs folder via `matchstick.yaml` config
18
+
file:
13
19
14
20
- To change the default tests location (./tests), add `testsFolder: path/to/tests_folder`
15
21
16
22
- To change the default libs location (./node_modules), add `libsFolder: path/to/node_modules`
17
23
18
-
- To change the default manifest location (./subgraph.yaml), add `manifestPath: path/to/subgraph.yaml`
24
+
- To change the default manifest location (./subgraph.yaml), add
25
+
`manifestPath: path/to/subgraph.yaml`
19
26
20
27
### Docker 🐳
21
-
The quickest way to use **Matchstick** "out of the box" is to build and run an ubuntu-based Docker container with a **Matchstick** image. Steps:
28
+
29
+
The quickest way to use **Matchstick** "out of the box" is to build and run an ubuntu-based Docker
30
+
container with a **Matchstick** image. Steps:
22
31
23
32
- Install [Docker](https://docs.docker.com/get-docker/) if you don't have it already.
24
33
25
-
- Create a file named `Dockerfile` in the root folder of your subgraph project, and paste [the contents of this file](https://github.com/LimeChain/demo-subgraph/blob/main/Dockerfile) there. Replace `<MATCHSTICK_VERSION>` placeholder with the desired matchstick version. You can find all available versions [here](https://github.com/LimeChain/matchstick/releases)
34
+
- Create a file named `Dockerfile` in the root folder of your subgraph project, and paste
35
+
[the contents of this file](https://github.com/LimeChain/demo-subgraph/blob/main/Dockerfile)
36
+
there. Replace `<MATCHSTICK_VERSION>` placeholder with the desired matchstick version. You can
37
+
find all available versions [here](https://github.com/LimeChain/matchstick/releases)
26
38
27
39
- Build a **Matchstick** image using the following command:
40
+
28
41
```
29
42
docker build -t matchstick .
30
43
```
31
44
32
-
- The build step might take a while, but once that's done we can quickly run our tests like this:
45
+
- The build step might take a while, but once that's done we can quickly run our tests like this:
33
46
34
47
```
35
48
docker run -it --rm --mount type=bind,source=<absolute/path/to/project>,target=/matchstick matchstick
36
49
```
37
50
38
-
❗ If you want to pass arguments to **Matchstick** (for instance to test only a specific datasource or to generate a test coverage report) you can do so like this:
51
+
❗ If you want to pass arguments to **Matchstick** (for instance to test only a specific datasource
52
+
or to generate a test coverage report) you can do so like this:
39
53
40
54
```
41
55
docker run -e ARGS="gravity" -it --rm --mount type=bind,source=<absolute/path/to/project>,target=/matchstick matchstick
42
56
```
43
57
44
-
❗ **Note:** The command will mount the project folder in the container, so you don't need to rebuild the image after every change to your code. Also any changes that happen to files during the run will persist on the host machine as well. [More info about docker bind mounts](https://docs.docker.com/storage/bind-mounts/)
58
+
❗ **Note:** The command will mount the project folder in the container, so you don't need to
59
+
rebuild the image after every change to your code. Also any changes that happen to files during the
60
+
run will persist on the host machine as well.
61
+
[More info about docker bind mounts](https://docs.docker.com/storage/bind-mounts/)
45
62
46
-
After that you can go straight to [the final setup step](https://github.com/LimeChain/matchstick/tree/dockerize#install-dependencies) and you'll be all set to start writing your first unit test.
63
+
After that you can go straight to
64
+
[the final setup step](https://github.com/LimeChain/matchstick/tree/dockerize#install-dependencies)
65
+
and you'll be all set to start writing your first unit test.
47
66
48
-
❗ If you have previously ran `graph test` you may encounter the following error during `docker build`: `error from sender: failed to xattr node_modules/binary-install-raw/bin/binary-<platform>: permission denied`. In this case create a file named `.dockerignore` in the root folder and add `node_modules/binary-install-raw/bin`
67
+
❗ If you have previously ran `graph test` you may encounter the following error during
68
+
`docker build`:
69
+
`error from sender: failed to xattr node_modules/binary-install-raw/bin/binary-<platform>: permission denied`.
70
+
In this case create a file named `.dockerignore` in the root folder and add
71
+
`node_modules/binary-install-raw/bin`
49
72
50
-
❗ Although using the Docker approach is easy, we highly recommend using **Matchstick** via OS-specific binary (which is downloaded automatically when you run `graph test`). The Docker approach should only be considered if for some reason you cannot get `graph test` to work, or if you just want to quickly try something out.
73
+
❗ Although using the Docker approach is easy, we highly recommend using **Matchstick** via
74
+
OS-specific binary (which is downloaded automatically when you run `graph test`). The Docker
75
+
approach should only be considered if for some reason you cannot get `graph test` to work, or if you
76
+
just want to quickly try something out.
51
77
52
78
### OS-specific release binaries ⚙️
53
-
The release binary comes in two flavours - for **МacOS** and **Linux**. To add **Matchstick** to your subgraph project just open up a terminal, navigate to the root folder of your project and simply run `graph test` - 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). Example usage: `graph test gravity`.
79
+
80
+
The release binary comes in two flavours - for **МacOS** and **Linux**. To add **Matchstick** to
81
+
your subgraph project just open up a terminal, navigate to the root folder of your project and
82
+
simply run `graph test` - it downloads the latest **Matchstick** binary and runs the specified test
83
+
or all tests in a test folder (or all existing tests if no datasource flag is specified). Example
84
+
usage: `graph test gravity`.
54
85
55
86
❗ If you don't have Postgres installed, you will need to install it. Instructions for that below:
56
-
❗❗❗ Since graph-node depends on diesel (and diesel requires a local postgres installation) we highly advise using the commands below as adding it in any other way may cause unexpected errors!
87
+
❗❗❗ Since graph-node depends on diesel (and diesel requires a local postgres installation) we
88
+
highly advise using the commands below as adding it in any other way may cause unexpected errors!
❗ Postgres installation command (depends on your distro):
107
+
73
108
```
74
109
sudo apt install postgresql
75
110
```
76
111
77
-
#### WSL (Windows Subsystem for Linux) 🤖
78
-
You can use Matchstick on WSL both using the Docker approach and the binary approach. As WSL can be a bit tricky, here's a few tips in case you encounter issues like `static BYTES = Symbol("Bytes") SyntaxError: Unexpected token =` or `<PROJECT_PATH>/node_modules/gluegun/build/index.js:13 throw up;`, or anything else that looks off:
112
+
#### WSL (Windows Subsystem for Linux) 🤖
79
113
80
-
Please make sure you're on a newer version of Node.js (graph-cli doesn't support **v10.19.0** anymore, and that is still the default version for new Ubuntu images on WSL. For instance Matchstick is confirmed to be working on WSL with **v18.1.0**, you can switch to it either via **nvm** or if you update your global Node.js). Don't forget to delete `node_modules` and to run `npm install` again after updating you nodejs! Then, make sure you have **libpq** installed, you can do that by running `sudo apt-get install libpq-dev`. And finally, do not use `graph test` (which uses your global installation of graph-cli and for some reason that looks like it's broken on WSL currently), instead use `yarn test` or `npm run test` (that will use the local, project-level instance of graph-cli, which works like a charm. For that you would of course need to have a "test" script in your package.json file which can be something as simple as `"test": "graph test"`).
114
+
You can use Matchstick on WSL both using the Docker approach and the binary approach. As WSL can be
115
+
a bit tricky, here's a few tips in case you encounter issues like
116
+
`static BYTES = Symbol("Bytes") SyntaxError: Unexpected token =` or
117
+
`<PROJECT_PATH>/node_modules/gluegun/build/index.js:13 throw up;`, or anything else that looks off:
118
+
119
+
Please make sure you're on a newer version of Node.js (graph-cli doesn't support **v10.19.0**
120
+
anymore, and that is still the default version for new Ubuntu images on WSL. For instance Matchstick
121
+
is confirmed to be working on WSL with **v18.1.0**, you can switch to it either via **nvm** or if
122
+
you update your global Node.js). Don't forget to delete `node_modules` and to run `npm install`
123
+
again after updating you nodejs! Then, make sure you have **libpq** installed, you can do that by
124
+
running `sudo apt-get install libpq-dev`. And finally, do not use `graph test` (which uses your
125
+
global installation of graph-cli and for some reason that looks like it's broken on WSL currently),
126
+
instead use `yarn test` or `npm run test` (that will use the local, project-level instance of
127
+
graph-cli, which works like a charm. For that you would of course need to have a "test" script in
128
+
your package.json file which can be something as simple as `"test": "graph test"`).
81
129
82
130
### Install dependencies
83
-
In order to use the test helper methods and run the tests, you will need to install the following dependencies:
131
+
132
+
In order to use the test helper methods and run the tests, you will need to install the following
133
+
dependencies:
84
134
85
135
```
86
136
yarn add --dev matchstick-as
87
137
```
88
138
89
-
Now you can jump straight to the [examples](https://github.com/LimeChain/demo-subgraph#readme"examples of tests") in our [demo-subgraph](https://github.com/LimeChain/demo-subgraph"demo-subgraph") and start your journey in Subgraph unit testing!
139
+
Now you can jump straight to the
140
+
[examples](https://github.com/LimeChain/demo-subgraph#readme'examples of tests') in our
141
+
[demo-subgraph](https://github.com/LimeChain/demo-subgraph'demo-subgraph') and start your journey
142
+
in Subgraph unit testing!
90
143
91
144
## Building from source
145
+
92
146
### Prerequisites
147
+
93
148
To build and run **Matchstick** you need to have the following installed on your system:
94
149
95
-
- Rust - [How to install Rust](https://www.rust-lang.org/en-US/install.html"How to install Rust")
150
+
- Rust - [How to install Rust](https://www.rust-lang.org/en-US/install.html'How to install Rust')
Clone this repository and run `cargo build`. If that executes successfully congratulations 🎉 you're all set.
100
154
101
-
**NOTE:***You may encounter an error, related to missing `libpq` dependencies on your system. In that case - install the missing dependencies (listed in the error log) with your package manager.*
155
+
Clone this repository and run `cargo build`. If that executes successfully congratulations 🎉 you're
156
+
all set.
157
+
158
+
**NOTE:**_You may encounter an error, related to missing `libpq` dependencies on your system. In
159
+
that case - install the missing dependencies (listed in the error log) with your package manager._
102
160
103
161
## Next steps 🎯
104
-
There is a lot of room for improvements to **Matchstick**. We're trying to gather as much feedback from subgraph developers as we can, to understand how we can solve the problems they face when building subgraphs, as well as how we can make the overall testing process as smooth and streamlined as possible.
105
162
106
-
There's a GitHub project board where we keep track of day to day work which you can check out [here](https://github.com/LimeChain/matchstick/projects/1"here").
163
+
There is a lot of room for improvements to **Matchstick**. We're trying to gather as much feedback
164
+
from subgraph developers as we can, to understand how we can solve the problems they face when
165
+
building subgraphs, as well as how we can make the overall testing process as smooth and streamlined
166
+
as possible.
167
+
168
+
There's a GitHub project board where we keep track of day to day work which you can check out
The **Matchstick** framework is built in **Rust** and acts as a wrapper for the generated WebAssembly module that contains the mappings and the unit tests. It passes the host function implementations down to the module, to be used in the tests (and in the mappings if needed). The framework also acts as a proxy for structs defined in the [graph-node repo](https://github.com/graphprotocol/graph-node/tree/master/graph"graph-node repo"), because it needs to pass down all the usual imports, as well as a few bonus/mocked ones glued on top.
177
+
The **Matchstick** framework is built in **Rust** and acts as a wrapper for the generated
178
+
WebAssembly module that contains the mappings and the unit tests. It passes the host function
179
+
implementations down to the module, to be used in the tests (and in the mappings if needed). The
180
+
framework also acts as a proxy for structs defined in the
0 commit comments