Test your integration

Use this guide when you need evidence that your application still calls TaxKit with the expected facts and handles expected failures.

Before you start

Choose SDK or HTTP in Choose SDK or HTTP API.
Keep one success case and one validation failure case.
Assert cents, report tags and error tags instead of snapshotting a full report.

Steps

Add a success test for the calculator you call.
Add a validation failure test that checks external input before calculation.
Run your app tests and the relevant TaxKit package test when working in this repo.

Example

import { assert, it } from "@effect/vitest";
import { Cents, aud } from "@taxkit/core/primitives";
import { GrossPay } from "@taxkit/rules-au-pay";
import { au } from "@taxkit/sdk/au";
import { Effect, Schema } from "effect";

it.effect("calculates weekly take-home pay", () =>
  Effect.promise(() =>
    au.pay.takeHomePay({
      grossPay: new GrossPay({
        amount: aud(Cents.make(165_400)),
        period: "weekly",
      }),
      taxFreeThresholdClaimed: true,
    })
  ).pipe(
    Effect.tap((report) =>
      Effect.sync(() => {
        assert.equal(report._tag, "TakeHomePayReport");
        assert.equal(report.netPay.cents, 130_100);
      })
    )
  )
);

it.effect("rejects external input before calculation", () =>
  Schema.decodeEffect(
    Schema.fromJsonString(au.calculations.takeHomePay.inputSchema)
  )('{"taxableIncome":{"_tag":"Money","cents":9000000,"currency":"AUD"}}').pipe(
    Effect.flip,
    Effect.tap((error) =>
      Effect.sync(() => assert.equal(error._tag, "SchemaError"))
    )
  )
);

Verify the result

Run your application's test command. Inside this repository, the SDK type and unit tests are:

bun run --filter=@taxkit/sdk test
bun run --filter=@taxkit/sdk test-types

Handle errors

Test the error tag your application relies on. Do not assert a full error message unless the message is part of your user-facing contract.

Read this page as Markdown