Use execution scripts

Execution scripts are shell commands Pie runs during a test, usually a curl call to your staging API. Use them to fetch or create test data, call your backend and reset state. Refer to a script in test steps with #{script-name}.

Before you start

• Know the command you want to run, typically curl against your staging or test environment. Never point a script at production.
• Run the command in your own terminal first and confirm it returns what you expect.
• Have the authentication the command needs. The command carries its own headers and tokens.

How scripts run

Pie decides when to run each script, based on what the test needs at that point:

1. You create a script with a name and a shell command.
2. You reference it in a test with #{script-name} in the prompt or steps.
3. During the run, Pie spots the reference and runs the command.
4. Pie captures the output (stdout) and keeps it for later steps.
5. Pie uses that output, for example by entering a generated phone number into a form field.

Scripts time out after 5 minutes. If a script doesn’t finish, the test carries on and Pie logs the failure.

Say a test reads “sign up with a unique phone number from #{get-unique-phone}”. Pie runs the script when it reaches the phone number field and types in the output. You don’t need a fixed step order for scripts.

Create a script

Open Scripts

In Settings, select Scripts. Each script’s badge shows how many test cases use it. Select the badge to see which ones.

Add the script

Select Add, enter a script name and the command, then select Add Script. The name becomes the #{name} reference, so use lowercase words joined by hyphens, such as create-banking-user.

Test the script

Select the script, then select Test. Enter a value for each parameter the command has, then select Run Test to see the output and any errors. Run it as many times as you need. For parameters, see Use parameters in scripts.

Reference the script in a test

Write #{script-name} in the test’s prompt or steps. See Create and edit tests.

Write the command

Scripts run on a Pie agent. Most are curl commands:

curl -X POST "https://your-staging-api.com/api/create-test-user" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_STAGING_TOKEN" \
  -d '{"role": "premium", "plan": "enterprise"}'

Your command should:

• Target your staging or test environment.
• Include authentication headers.
• Return data in a consistent format. JSON works best.
• Be idempotent where possible, so it’s safe to run more than once.

Reference scripts in test cases

Use #{script-name} anywhere in a test case’s prompt or steps.

One script. Pie runs get-unique-phone when it needs the phone number and uses the output in the signup form:

Sign up for a new account. Use #{get-unique-phone} to generate
a phone number for registration. Complete the signup flow and
verify the user lands on the dashboard.

Several scripts. A test can reference more than one. They run in the order Pie needs them:

Create a new banking user by calling #{create-new-banking-user}.
Use the returned credentials to log in. Then call #{get-valid-debit-card}
to fetch payment details and complete the card linking flow.

Chained outputs. Output carries forward through the test, so a later script can use a value an earlier one returned:

Call #{create-test-user} to create a new user. Then call
#{generate-otp} using the phone number from the previous step.
Enter the OTP to complete verification.

Seed and reset test data

Tests that change data need a known starting state, and they should leave the state clean for the next run. Use one script to seed the data a flow needs and another to reset it, and call both from the test.

Name both in the test that uses them:

Call #{seed-products}. Add the first product to the cart and check out.
Verify the order confirmation appears. Then call #{reset-cart}.

Make each command safe to run twice and scope it to the test tenant or test user, so a reset never touches other data. For fixtures, namespaces and reset strategies that hold up across concurrent runs, see Prepare identity, access, and test data.

Common uses

Generate unique test data. Tests that create accounts need a new identifier on every run.

Complete verification steps from your backend. When a flow needs a one-time code or a verification status, call a test endpoint on your own backend that returns it.

Fetch environment-specific data. Tests need data that matches your staging environment.

Example: a loan application

A loan approval test needs a user with a specific credit score, a valid identifier and a verified identity. Script all three, so every run starts with fresh ones.

Create three scripts:

# create-prequalified-user
curl -X POST "https://staging-api.yourbank.com/test/create-user" \
  -H "Authorization: Bearer STAGING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"credit_score": 750, "income": 85000, "employment": "verified"}'

# get-test-ssn
curl -X GET "https://staging-api.yourbank.com/test/generate-ssn" \
  -H "Authorization: Bearer STAGING_TOKEN"

# generate-otp
curl -X POST "https://staging-api.yourbank.com/test/generate-otp" \
  -H "Authorization: Bearer STAGING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "{{use the phone number from create-prequalified-user}}"}'

Then write the test:

Test the loan application flow end-to-end:
1. Call #{create-prequalified-user} to create a test user with good credit
2. Log in with the returned credentials
3. Navigate to "Apply for Loan"
4. Enter the SSN from #{get-test-ssn}
5. When prompted for OTP, call #{generate-otp} and enter the code
6. Complete the loan application form
7. Verify the loan is pre-approved with an offer displayed

During the run, Pie calls create-prequalified-user and gets back {"phone": "5551234567", "password": "TestPass1"}, then logs in with those values. At the SSN field it calls get-test-ssn. When the flow asks for a code, it calls generate-otp with the phone number from the first script. Then it completes the flow and checks the offer.

Name and keep scripts

Use verb-first names that say what the script does. The name is the #{name} reference, so it should read well in a sentence.

• Target staging, never production. Scripts run on every test execution.
• Keep each script focused. One script does one thing. Chain scripts rather than building one complex command.
• Return meaningful errors. A clear error message from your API lets Pie report what went wrong.

To change a script, select it and open the three-dot menu:

• Edit: rename it or change the command, then select Save Changes.
• History: view or compare earlier versions and restore one. Pie saves the current content as a new version before it restores.
• Delete: remove the script. If test cases still use it, you’ll see how many before you confirm.

What you’ll see

Your new script shows in the list with a badge that counts the test cases using it. In a run, Pie calls the script at the step that needs it and uses the output in the steps that follow.

If a script fails

• The script doesn’t run. Check that the name in the test matches the script name exactly, including case. Run the command in a terminal, and confirm your server accepts requests from outside your network.
• Authentication errors. Check that the token is current, that the Authorization header is formatted correctly, and that your test server accepts external addresses.
• The output isn’t used. Confirm the command returns data rather than an empty response, in a parseable format such as JSON. If you chain scripts, check that the earlier script completed.
• The script times out. Scripts stop after 5 minutes. Speed up the underlying call, split long work into smaller scripts, or make the endpoint asynchronous and poll.

Do this from your agent or API

Your agent can work with scripts through the get_scripts, create_script, update_script and delete_script MCP tools. The API equivalents are GET /v1/scripts and POST /v1/scripts. delete_script won’t delete a script that test cases still reference, and it lists those test cases. See MCP tools and the API overview.

Next steps