Get started

Install Pup and check your first supertest. Use your own code or try the example project from Welcome to Pup.

Using an AI agent?

Give your agent the Pup skill to handle setup, write supertests, and run checks for you.

Language support#

Pup supports the following languages:

Choose your programming language to see the relevant instructions and examples throughout the docs: Python You can change this anytime using the language selector in the navigation menu or a code snippet.

Install Pup#

Run the Pup installer:

$ curl -fsSL https://get.schematic.tech/pup.sh | sh

Follow the installer’s instructions, including restarting your terminal if requested. Then check the installed version:

$ pup --version
  pup 0.5.1

Log in to Schematic#

Sign in to platform.schematic.tech and generate an API key. Then run pup login and enter the key when prompted:

$ pup login
  ? Pup API key › [hidden]
  ✓ Logged in as you@example.com

Prepare your project#

Use your own project by adding supertest support below, or set up the example for your language instead. To see instructions for your programming language, select it here: Python or change it anytime using the language selector in the navigation menu or a code snippet.

Add supertest support#

Install schematic-supertest in your project’s active Python environment (Python 3.11 or later). The package provides @supertest and assume.

Add schematic-supertest as a development dependency in your Cargo project. The crate provides #[supertest] and assume, imported from schematic. Use Rust 1.85 or later.

Add schematic.h to your project and put its directory on your compiler’s include path. The header provides SUPERTEST and SUPERTEST_ASSUME. You can download the header or use the commands below.

Use #include <schematic.h> in your supertest and compile with -Iinclude.

Run these commands in the .NET project that compiles your supertests. SchematicTech.Supertest provides [Supertest] and Assumptions.Assume. The examples also use xunit.v3.assert for assertions.

Install schematic-supertest as a development dependency in your JavaScript project. The package provides supertest and assume. Use Node.js 22 or later. The examples use ES modules, with "type": "module" in package.json.

Add these entries to the <dependencies> section of your Maven project’s pom.xml. The supertest package provides @Supertest and Assumptions.assume. The examples use JUnit for assertions.

Analyze schematic.vhd into the same work library as your supertests using VHDL-2008. The package provides supertest_assume. Mark each supertest process with --% supertest. You can download the package or use the commands below.

$ python -m pip install schematic-supertest

$ cargo add --dev schematic-supertest

$ mkdir -p include
$ curl -fsSL https://raw.githubusercontent.com/schematic-tech/supertest-c/v0.1.1/include/schematic.h -o include/schematic.h

$ dotnet add package SchematicTech.Supertest
$ dotnet add package xunit.v3.assert

$ npm install --save-dev schematic-supertest

<dependencies>
  <dependency>
    <groupId>tech.schematic.supertest</groupId>
    <artifactId>schematic-supertest</artifactId>
    <version>0.1.0</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.13.2</version>
    <scope>test</scope>
  </dependency>
</dependencies>

$ mkdir -p include
$ curl -fsSL https://raw.githubusercontent.com/schematic-tech/supertest-vhdl/v0.1.1/src/schematic.vhd -o include/schematic.vhd
$ ghdl -a --std=08 include/schematic.vhd

We recommend keeping supertests in tests/. Run cargo check --tests to check that they compile. Use Pup to check their requirements; cargo test does not run functions marked only with #[supertest].

We recommend keeping supertests in src/test/java/, where Maven makes these test dependencies available.

You can use your project’s existing assertion library instead of adding the one used in these examples.

Include use work.schematic.all; in the context of each design unit that calls supertest_assume. Analyze the package before those design units, using the same work library and VHDL standard.

Then write a supertest for your code and link your repository.

Set up the example project#

The example includes a small program with a bug and a supertest that exposes it.

Clone the supertest library for your language and prepare its text-tools example:

With GHDL and Make installed, clone the supertest library and prepare its saturating-increment example:

Use the .NET 8 SDK to build this example.

Use Node.js 22 or later to build this example.

Use JDK 17 or later. On Windows, use mvnw.cmd in place of ./mvnw.

$ git clone https://github.com/schematic-tech/supertest-python.git
$ cd supertest-python/examples/text-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
$ python -m pip install -r requirements.txt

$ git clone https://github.com/schematic-tech/supertest-rust.git
$ cd supertest-rust/examples/text-tools
$ cargo check --tests

$ git clone https://github.com/schematic-tech/supertest-c.git
$ cd supertest-c/examples/text-tools
$ make

$ git clone https://github.com/schematic-tech/supertest-csharp.git
$ cd supertest-csharp/examples/text-tools
$ dotnet build -c Release

$ git clone https://github.com/schematic-tech/supertest-javascript.git
$ cd supertest-javascript
$ npm ci
$ npm run build
$ cd examples/text-tools

$ git clone https://github.com/schematic-tech/supertest-java.git
$ cd supertest-java
$ ./mvnw install
$ ./mvnw -f examples/text-tools/pom.xml test-compile
$ cd examples/text-tools

$ git clone https://github.com/schematic-tech/supertest-vhdl.git
$ cd supertest-vhdl/examples/saturating-increment
$ make

Link your repository#

Pup links the whole Git repository, even when you run it from a subdirectory, and syncs its current committed source to Schematic. See Source and commits for which files Pup includes and how to exclude files.

The repository needs at least one commit, which a clone already has. From the directory you want to check, run:

$ pup link .
  ✓ Linked supertest-python · main · 8e44bea
  Next: pup check

$ pup link .
  ✓ Linked supertest-rust · main · 8e44bea
  Next: pup check

$ pup link .
  ✓ Linked supertest-c · main · 8e44bea
  Next: pup check

$ pup link .
  ✓ Linked supertest-csharp · main · 8e44bea
  Next: pup check

$ pup link .
  ✓ Linked supertest-javascript · main · 8e44bea
  Next: pup check

$ pup link .
  ✓ Linked supertest-java · main · 8e44bea
  Next: pup check

$ pup link .
  ✓ Linked supertest-vhdl · main · 8e44bea
  Next: pup check

Your repository name, branch, and commit may differ from the example output.

Run a check#

Run your first check from your project directory:

$ pup check .

The . tells Pup to check supertests in the current directory and its subdirectories. See the pup check reference for options and other ways to select supertests.

The Welcome to Pup walkthrough follows the example through finding a bug, reviewing a fix, and verifying the corrected behavior.

Where to go next#

• Writing supertests explains inputs, assumptions, and assertions.
• Using AI agents shows how an agent can help you set up Pup, write supertests, and run checks.
• Check commands covers selecting supertests, following progress, and reviewing results.