# Assertions

Assertions can be made from any unit test framework with a [global setup](https://arktype.io/docs/attest#global-setup).

### Types and values

```ts
import { attest } from "@ark/attest"
import { type } from "arktype"

const Even = type("number%2")
// asserts Even.infer is exactly number
attest<number>(Even.infer)
// make assertions about types and values seamlessly
attest(Even.infer).type.toString.snap("number")
// including object literals- no more long inline strings!
attest(Even.json).snap({
	domain: "number",
	divisor: 2
})
```

### Errors

```ts
import { attest } from "@ark/attest"
import { type } from "arktype"

// Check type errors, runtime errors, or both at the same time!
// @ts-expect-error
attest(() => type("number%0")).throwsAndHasTypeError(
	"% operator must be followed by a non-zero integer literal (was 0)"
)
// @ts-expect-error
attest(() => type({ "[object]": "string" })).type.errors(
	"Indexed key definition 'object' must be a string or symbol"
)
```

### Completions

```ts
import { attest } from "@ark/attest"
import { type } from "arktype"

// snapshot expected completions for any string literal!
// @ts-expect-error (if your expression would throw, prepend () =>)
attest(() => type({ b: "b" })).completions({
	b: ["bigint", "boolean"]
})

type Legends = { faker?: "🐐"; [others: string]: unknown }
// works for keys or index access as well (may need prettier-ignore to avoid removing quotes)
// prettier-ignore
attest({ "f": "🐐" } as Legends).completions({ "f": ["faker"] })
```

### JSDoc

```ts
import { attest } from "@ark/attest"
import { type } from "arktype"

// match or snapshot expected jsdoc associated with the value passed to attest
const T = type({
	/** FOO */
	foo: "string"
})

const out = T.assert({ foo: "foo" })

attest(out.foo).jsdoc.snap("FOO")
```

### Runtime logic

Flexibly combine runtime logic with type assertions to customize your tests beyond what is possible from pure static-analysis based type testing tools.

```ts
import { attest } from "@ark/attest"
import { type } from "arktype"
import ts from "typescript"

const arrayOf = type("<t>", "t[]")
const numericArray = arrayOf("number | bigint")

if (ts.version.startsWith("5")) {
	// this assertion will only occur when testing TypeScript 5+!
	attest<(number | bigint)[]>(numericArray.infer)
}
```

### Instantiations

Snapshot the number of type instantiations contributed by the enclosing test.

```ts
import { attest } from "@ark/attest"
import { type } from "arktype"

it("discriminated union", () => {
	const User = type({
		kind: "'admin'",
		"powers?": "string[]"
	})
		.or({
			kind: "'superadmin'",
			"superpowers?": "string[]"
		})
		.or({
			kind: "'pleb'"
		})

	attest.instantiations([7574, "instantiations"])
})
```