matchstick

GitHub 横幅 - 由 LimeChain 制作-1

👋 欢迎使用 Matchstick - The Graph 协议的单元测试框架。在沙盒环境中尝试您的映射逻辑，确保在部署您出色的子图时处理程序能正确运行！

快速开始 🚀

Matchstick 依赖于一个辅助库 - matchstick-as，该库用 AssemblyScript 编写，并在单元测试中作为导入使用。

配置 ⚙️

Matchstick 可以通过 matchstick.yaml 配置文件来使用自定义的测试和库文件夹：

要更改默认测试位置（./tests），添加 testsFolder: path/to/tests_folder
要更改默认库位置（./node_modules），添加 libsFolder: path/to/node_modules
要更改默认清单位置（./subgraph.yaml），添加 manifestPath: path/to/subgraph.yaml

Docker 🐳

使用 Matchstick 最快捷的方法是构建并运行一个基于 Ubuntu 的 Docker 容器，其中包含 Matchstick 镜像。步骤如下：

如果还没有安装 Docker，请先安装 Docker。
在子图项目的根文件夹中创建一个名为 Dockerfile 的文件，并将此文件的内容粘贴到其中。将 <MATCHSTICK_VERSION> 占位符替换为所需的 matchstick 版本。您可以在这里找到所有可用版本。
使用以下命令构建 Matchstick 镜像：

docker build -t matchstick .

构建步骤可能需要一些时间，但完成后我们可以快速运行测试：

docker run -it --rm --mount type=bind,source=<项目的绝对路径>,target=/matchstick matchstick

❗ 如果您想向 Matchstick 传递参数（例如只测试特定的数据源或生成测试覆盖率报告），可以这样做：

docker run -e ARGS="gravity" -it --rm --mount type=bind,source=<项目的绝对路径>,target=/matchstick matchstick

❗ 注意： 该命令会将项目文件夹挂载到容器中，因此每次更改代码后无需重新构建镜像。此外，运行期间对文件的任何更改也会保留在主机上。有关 docker 绑定挂载的更多信息

之后，您可以直接进入最后的设置步骤，就可以开始编写您的第一个单元测试了。

❗ 如果您之前运行过 graph test，在 docker build 过程中可能会遇到以下错误：error from sender: failed to xattr node_modules/binary-install-raw/bin/binary-<platform>: permission denied。在这种情况下，在根文件夹中创建一个名为 .dockerignore 的文件，并添加 node_modules/binary-install-raw/bin

❗ 虽然使用 Docker 方法很简单，但我们强烈建议通过特定操作系统的二进制文件使用 Matchstick（当您运行 graph test 时会自动下载）。只有在由于某些原因无法使用 graph test，或者您只是想快速尝试一下时，才应考虑使用 Docker 方法。

特定操作系统的发布二进制文件 ⚙️

发布的二进制文件有两种版本 - МacOS 和 Linux。要将 Matchstick 添加到您的子图项目中，只需打开终端，导航到项目的根文件夹，然后运行 graph test - 它会下载最新的 Matchstick 二进制文件并运行指定的测试或测试文件夹中的所有测试（如果未指定数据源标志，则运行所有现有测试）。示例用法：graph test gravity。

❗ 如果您没有安装 Postgres，则需要安装它。以下是安装说明： ❗❗❗ 由于 graph-node 依赖于 diesel（而 diesel 需要本地 postgres 安装），我们强烈建议使用以下命令进行安装，因为以其他方式添加可能会导致意外错误！

MacOS

❗ Postgres 安装命令：

brew install postgresql@14

然后创建指向库的新符号链接：

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

Linux 🐧

❗ Postgres 安装命令（取决于您的发行版）：

sudo apt install postgresql

WSL（Windows 子系统 for Linux）🤖

您可以在 WSL 上使用 Docker 方法和二进制方法来使用 Matchstick。由于 WSL 可能有些棘手，以下是一些提示，以防遇到诸如 static BYTES = Symbol("Bytes") SyntaxError: Unexpected token = 或 <PROJECT_PATH>/node_modules/gluegun/build/index.js:13 throw up; 或其他看起来不对劲的问题：

请确保您使用的是较新版本的 Node.js（graph-cli 不再支持 v10.19.0，而这仍然是 WSL 上新 Ubuntu 镜像的默认版本。例如，Matchstick 在 WSL 上使用 v18.1.0 时已确认可以正常工作，您可以通过 nvm 切换到它，或者更新全局 Node.js）。更新 nodejs 后，别忘了删除 node_modules 并重新运行 npm install！然后，确保安装了 libpq，可以通过运行 sudo apt-get install libpq-dev 来安装。最后，不要使用 graph test（它使用全局安装的 graph-cli，目前在 WSL 上似乎有问题），而是使用 yarn test 或 npm run test（这将使用本地项目级别的 graph-cli 实例，它可以正常工作。为此，您当然需要在 package.json 文件中有一个"test"脚本，它可以简单到 "test": "graph test"）。

安装依赖

为了使用测试辅助方法并运行测试，您需要安装以下依赖：

yarn add --dev matchstick-as

现在您可以直接跳转到我们 demo-subgraph 中的示例，开始您的子图单元测试之旅！

从源代码构建

先决条件

要构建和运行 Matchstick，您需要在系统上安装以下内容：

Rust - 如何安装 Rust
PostgreSQL – PostgreSQL 下载

设置

克隆此存储库并运行 cargo build。如果执行成功，恭喜 🎉 您已经准备就绪。

注意： 您可能会遇到与系统上缺少 libpq 依赖项相关的错误。在这种情况下，请使用包管理器安装缺少的依赖项（错误日志中列出）。

下一步 🎯

Matchstick 还有很大的改进空间。我们正试图从子图开发者那里收集尽可能多的反馈，以了解如何解决他们在构建子图时面临的问题，以及如何使整个测试过程尽可能顺畅和流畅。

我们有一个 GitHub 项目板，用于跟踪日常工作，您可以在这里查看。

您可以在这里查看完整的任务列表。

使用的技术 💻

图表-调整大小

Matchstick 框架是用 Rust 构建的，作为包含映射和单元测试的生成的 WebAssembly 模块的包装器。它将主机函数实现传递给模块，以便在测试中使用（如果需要，也可以在映射中使用）。该框架还充当 graph-node 仓库中定义的结构的代理，因为它需要传递所有常用导入，以及一些粘合在顶部的额外/模拟导入。