Docs Técnicas

TREA JS Test Runner

@atlas/trea-js is the TypeScript client and test-helper layer for the local TREA Dev Chain.

O conteúdo abaixo vem das fontes técnicas do repositório e é prerenderizado no site para leitura direta por pessoas, crawlers e agentes.

@atlas/trea-js is the TypeScript client and test-helper layer for the local TREA Dev Chain.

It lets contract tests interact with the real Dev Chain HTTP API without using Rust internals such as BlockExecutor or ledger stores directly.

Package Layout

The package lives at:

text

packages/trea-js/

Root exports are browser-safe and back the existing brand-site TREA demos:

import { TreaClient, argInt, formatError } from "@atlas/trea-js";

Node-only test helpers are exported as subpaths:

import { DevChainProcess, DevChainClient } from "@atlas/trea-js/dev-chain";
import { assertReceipt, assertStateRoot, assertStorageValue } from "@atlas/trea-js/test";

Dev Chain E2E Shape

For the package-level smoke project, put contracts in contracts/, compile them with the TREA CLI, then run the Dev Chain test:

cd packages/trea-js
npm run compile
npm run test:devnet

npm run compile checks contracts/dev_counter.trea with trea build. npm run test:devnet starts the real atlas-dev-chain binary in dev mode, publishes the contract, deploys it, calls its transaction functions, simulates its view functions and asserts receipts/state.

A contract test should access the contract through a small typed wrapper rather than poking raw storage first. The included DevCounter wrapper exposes the contract functions directly:

import test from "node:test";
import assert from "node:assert/strict";
import { DevChainProcess } from "@atlas/trea-js/dev-chain";
import { assertReceipt, assertStateRoot } from "@atlas/trea-js/test";
import { deployDevCounter } from "../../examples/dev-counter.js";

test("DevCounter exposes current() and increment()", async () => {
  const chain = await DevChainProcess.start({ repoRoot: process.cwd() });

  try {
    const { contract } = await deployDevCounter(chain.client);

    const before = await contract.current();   // @view via simulate
    const receipt = await contract.increment(7); // @tx via call
    const after = await contract.current();

    assert.equal(before, 0);
    assert.equal(after, 7);
    assertReceipt(receipt);
    assertStateRoot(await chain.client.status());
  } finally {
    await chain.stop();
  }
});

The lower-level client is still available when a test needs raw Dev Chain control:

await client.publish({ artifactId, source });
await client.deploy({ artifactId, contractId });
await client.call({ contractId, entrypoint: "increment", args: [argInt(7)] });
await client.simulate({ contractId, entrypoint: "current" });

Fixtures

treaDevToml() builds deterministic trea.dev.toml content for tests that want startup fixtures and named snapshots:

import { treaDevToml } from "@atlas/trea-js/dev-chain";

const config = treaDevToml({
  seed: "contract-test-seed",
  fixtures: [
    {
      name: "counter-ready",
      autoSnapshot: true,
      steps: [
        { op: "publish", artifact_id: "dev-counter:v1", source: sourceCode },
        { op: "deploy", artifact_id: "dev-counter:v1", contract_id: "dev-counter-1" },
      ],
    },
  ],
});

The package acceptance test at packages/trea-js/test/dev-chain.e2e.test.ts starts two Dev Chain instances with the same config and compares receipts and state roots.