Introduction

Get started#

Install Pup, connect it to your Schematic account, and check a supertest against a Git commit.

Install Pup#

The installer downloads the appropriate Pup release from GitHub and places the binary in your user path.

macOS and Linux#

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

Windows#

Run the installer from PowerShell:

irm https://get.schematic.com/pup.ps1 | iex

Open a new terminal if the installer updates your PATH, then confirm that Pup is available:

$ pup --version
pup 0.1.0

Shell completion#

The installer enables shell completion when it can do so safely. Install or repair it explicitly with:

$ pup completion install
✓ Installed zsh completions

Pup detects Bash, Fish, PowerShell, or zsh. Pass the shell name when detection is not appropriate, such as pup completion install fish. Completion covers commands, paths, and locally discoverable supertest names after ::. The lower-level pup completion <shell> command prints a completion script to standard output for package managers and manually managed shell profiles.

Log in to Schematic#

$ pup login
Opening your browser to log in to Schematic...
✓ Logged in · you@example.com · Your organization

Pup opens a browser and completes OAuth using a short-lived local callback. If the browser cannot open, Pup prints a URL you can visit yourself. Accounts with access to more than one Schematic organization are prompted to choose one.

See Account commands for credential storage and logout behavior.

Link the repository#

Run this command from the repository root:

$ pup repo link .
● text-tools · main@a81d7c2 · preparing 12%

Pup links this repository and begins preparing its current commit. It then watches for later commits in the background. Linking does not push to a Git remote or change your repository.

Check when the commit is ready:

$ pup repo status
✓ text-tools · main@a81d7c2 · ready

Review .pupignore before linking a sensitive repository. Read Source and commits for the complete eligibility and privacy behavior.

Add the Schematic library#

Add the Schematic authoring library to your project:

cargo add schematic-supertests

python -m pip install schematic-supertests

bundle add schematic-supertests

The library supplies the supertest declaration and assume operation. Pup performs the checking remotely.

Write a first supertest#

For this walkthrough, suppose the repository contains the collapse_spaces function from Welcome to Pup. Create a supertest stating that once text has been normalized, another call must not change it:

use schematic::supertest;

#[supertest]
fn normalizing_twice_changes_nothing(text: String) {
    let once = collapse_spaces(&text);
    let twice = collapse_spaces(&once);

    assert_eq!(twice, once);
}

from schematic import *

@supertest
def normalizing_twice_changes_nothing(text: str) -> None:
    once = collapse_spaces(text)
    twice = collapse_spaces(once)

    assert twice == once

require "schematic"

Schematic.supertest(
  "normalizing_twice_changes_nothing",
  text: String
) do |text|
  once = collapse_spaces(text)
  twice = collapse_spaces(once)

  assert twice == once
end

Parameters represent all values of their declared type. This claim applies to every string, including empty strings and strings with long runs of spaces.

Start the check#

Bare pup check checks every supertest in the linked repository. Add --wait to keep this terminal attached until every selected row finishes.

Checks normally use your current commit. Because this supertest has not been committed, Pup asks whether to include the uncommitted changes:

$ pup check --wait
Uncommitted changes found. Check them as a temporary Pup commit? [Y/n] y

text-tools · 4e92c1a · temporary Pup commit · based on a81d7c2 · .

× normalizing_twice_changes_nothing · failed · ref 43

$ pup check --wait
Uncommitted changes found. Check them as a temporary Pup commit? [Y/n] y

text-tools · 4e92c1a · temporary Pup commit · based on a81d7c2 · .

× normalizing_twice_changes_nothing · failed · ref 43

$ pup check --wait
Uncommitted changes found. Check them as a temporary Pup commit? [Y/n] y

text-tools · 4e92c1a · temporary Pup commit · based on a81d7c2 · .

× normalizing_twice_changes_nothing · failed · ref 43

If you commit the file first, Pup checks that commit without prompting. Source and commits explains temporary Pup commits.

Inspect the counterexample#

Inspect the most recent check and its counterexample:

$ pup check status
text-tools · supertests/normalize_spaces.rs::normalizing_twice_changes_nothing

    COMMIT  · STATUS · WHEN   · REF
› × 4e92c1a · failed · 1m ago ·  43

Problem P1
  Normalization is not idempotent
  collapse_spaces replaces only one pair of spaces per call.

Confirmed counterexample
  text   = "hello   world"
  once   = "hello  world"
  twice  = "hello world"

$ pup check status
text-tools · supertests/normalize_spaces.py::normalizing_twice_changes_nothing

    COMMIT  · STATUS · WHEN   · REF
› × 4e92c1a · failed · 1m ago ·  43

Problem P1
  Normalization is not idempotent
  collapse_spaces replaces only one pair of spaces per call.

Confirmed counterexample
  text   = "hello   world"
  once   = "hello  world"
  twice  = "hello world"

$ pup check status
text-tools · supertests/normalize_spaces.rb::normalizing_twice_changes_nothing

    COMMIT  · STATUS · WHEN   · REF
› × 4e92c1a · failed · 1m ago ·  43

Problem P1
  Normalization is not idempotent
  collapse_spaces replaces only one pair of spaces per call.

Confirmed counterexample
  text   = "hello   world"
  once   = "hello  world"
  twice  = "hello world"

REF 43 is a short reference for this exact attempt in the linked repository. You rarely need to type it, but pup check status 43 returns to this attempt later.

If you started without --wait, observe the latest invocation without copying any reference:

$ pup check status --wait

The focused history remains visible while the active row and any emerging evidence update in place. Ctrl-C detaches your terminal without canceling the check.

Fix and recheck the supertest#

Use the counterexample to fix collapse_spaces, then commit the corrected source:

$ git add .
$ git commit -m "Fully collapse repeated spaces"

Get quick feedback by rechecking Problems from the latest invocation against the new commit:

$ pup check --problems --wait
Rechecking 1 problematic supertest from 4e92c1a.
text-tools · 91ab40e · .

✓ normalizing_twice_changes_nothing · 0 problems · ref 44

Pup connects the new attempt to the failure from the earlier commit when you inspect status:

$ pup check status
text-tools · supertests/normalize_spaces.rs::normalizing_twice_changes_nothing

    COMMIT  · STATUS     · WHEN    · REF
› ✓ 91ab40e · 0 problems · 12s ago ·  44
  × 4e92c1a · failed     · 4m ago  ·  43

$ pup check status
text-tools · supertests/normalize_spaces.py::normalizing_twice_changes_nothing

    COMMIT  · STATUS     · WHEN    · REF
› ✓ 91ab40e · 0 problems · 12s ago ·  44
  × 4e92c1a · failed     · 4m ago  ·  43

$ pup check status
text-tools · supertests/normalize_spaces.rb::normalizing_twice_changes_nothing

    COMMIT  · STATUS     · WHEN    · REF
› ✓ 91ab40e · 0 problems · 12s ago ·  44
  × 4e92c1a · failed     · 4m ago  ·  43

A targeted recheck is fast feedback, not a claim that the entire new commit has passed. Finish by checking the complete repository:

$ pup check --wait

Pup reuses the existing successful attempt in that full invocation because it already checked the same supertest at commit 91ab40e. Other supertests receive their own attempts for that commit.

This is the expected development loop:

Run pup check, with --wait when you want to stay attached.
Inspect the latest results with pup check status.
Fix and commit the source.
Run pup check --problems for quick feedback, optionally with --wait.
Inspect the update with pup check status.
Run pup check again to confirm the complete new commit.

Pass --prove when you need Pup to establish that the selected claims hold for the commit.

Where to go next#

Writing supertests explains inputs, assumptions, assertions, and selectors.
Repository commands covers linking, commit preparation, and unlinking.
Check commands covers selectors, progress, Problems, results, and attempt context.