# Test your form

Try your form as much as you like. Tests are kept apart from your real submissions, don't count
on your plan, and never reach your recipients. There's no test mode to turn on or remember to
turn off: Formerie looks at each submission and tells you what happened.

## Test from your computer

Point your site at the form while it runs on a local dev server. That's all the setup there is.

A request from `localhost`, `127.0.0.1` or `[::1]` with a port, such as `http://localhost:5173`, is
stored as a test as long as that address isn't in the form's **Allowed websites**. The form must be
published first.

The response looks like a normal success, with one more part that says it was a test:

```json
{
  "ok": true,
  "submissionId": "tst_p6dr8wq2j7tkan",
  "submissionUid": "tst_p6dr8wq2j7tkan",
  "status": "accepted",
  "test": {
    "source": "loopback",
    "version": { "kind": "published", "number": 3 },
    "nobodyNotified": true,
    "expiresAt": "2026-11-30T12:00:00.000Z",
    "reason": "http://localhost:5173 is not an allowed website for this form, so this was stored as a test.",
    "docs": "https://docs.formerie.com/guides/test-your-form/"
  },
  "delivery": { "queued": false, "status": "test" },
  "version": { "number": 3 }
}
```

The response also carries an `X-Formerie-Test` header. A real submission never has either.

If your form requires human verification, it still needs a token, so you know the widget is wired up.
Formerie gives your local page an always-pass Turnstile key, and doesn't check the token.

## Test a staging website

Add its address under **Test websites** on the form's **Tests** tab, such as
`https://staging.example.com`. Submissions from it are then stored as tests, and its pages get the same
always-pass key. A website that's in **Allowed websites** stays real, so it can't be added here. If real
submissions came from an address in the last 30 days, Formerie asks you to confirm first.

## Share a try link

Choose **Create a link** on the **Tests** tab, and send it to anyone. They don't need an account. They see
the form with a banner saying it's a test, and you get the email it sends. No one else does.

A link can show the published form or the current draft, including a form that was never published. It lasts
7 days. Revoke it whenever you like, and it stops at once.

Add `?simulate=closed`, `?simulate=full` or `?simulate=not_open` to a link's submit address to see the
message a visitor would get in that state.

## Test from a server or CI

Create a key on the **Tests** tab, then send it in a header. A key is shown once, and only works for its own
form.

```bash
curl -X POST https://forms.formerie.com/your-workspace/your-form/submit \
  -H "Content-Type: application/json" \
  -H "X-Formerie-Test-Key: frmtest_your_key" \
  -d '{"fields":{"email":"sample@example.com"}}'
```

- A wrong, revoked or expired key gets `TEST_KEY_INVALID`, and nothing is stored or sent. It never goes out
  as a real submission.
- Keys don't work from a browser, so one can't end up in your site's code by accident. Use a test website for
  that.
- Add `X-Formerie-Test-Version: draft` to test the draft of a published form, and
  `X-Formerie-Test-Simulate: closed`, `full` or `not_open` to see a refusal.
- From a website in **Allowed websites**, the key is ignored and the submission is real. The response carries a
  `TEST_KEY_IGNORED_ORIGIN_LISTED` notice.

A key left in a production server files everything as tests, so check **Last real submission** after you go
live. Tests sent with a key are deleted after 7 days.

## See the email

Every test keeps the email a real submission would have sent, and how many recipients would have received it.
Local and staging tests send nothing. To see it in your inbox, open the entry and choose **Send to me**. It goes
only to your confirmed login address, marked `[Test]`, with no copies and no reply-to. A try link emails its
creator in the same way, and a key does if you turned that on when creating it. Test emails don't count on your
plan. A link or key can send 20 a day, and an account 50.

## What counts as real

Going live needs no switch either, because real traffic is real by rule:

- A submission from a website in **Allowed websites** is always real, including a local address you
  listed yourself.
- A submission with no `Origin` header, such as one from your server or a native app, is always real.
- Every other address gets `FORBIDDEN_ORIGIN`, as it would without tests.

Mobile apps often use `https://localhost` or `capacitor://localhost`. Those have no port, so they're never
tests. `https://localhost` can be added to **Allowed websites**. Custom schemes such as `capacitor://` can't
be added today, so send those submissions from your server.

## See your tests

Open the form and choose **Tests**. Each entry shows its answers, where it came from, and the email a
real submission would have sent. The form's overview shows your last real submission beside your last
test, so you can tell at a glance that real responses are coming in.

Tests stay out of your **Submissions** list, your exports, your stats and your plan's usage.

Tests are deleted after 30 days, or 7 with a test key. You can delete one, or all of a form's, whenever you like. Use sample
data where you can: a test can hold real personal information if you type it in.

## If a test was really a person

A real person can land in tests if a shipped app runs on a local address, or a key stayed on a server. When
entries come from many addresses in a day, or from a mobile app, Formerie marks them **May be real**, emails
owners and admins, and holds off on deleting them for up to 90 more days.

Open an entry to choose:

- **Deliver as real** makes it a real submission. It's checked against the published form, emails your recipients,
  and counts on your plan. Owners, admins and people who manage submissions can do this, for any test.
- **They're tests** clears the marks, and those entries are deleted as usual.

## Test limits

Tests have their own limits, separate from real submissions, so testing can't slow down your visitors.

| | Local computer | Test website | Test key | Try link |
| --- | --- | --- | --- | --- |
| In a minute | 30 from one address | 60 | 300 | 30 |
| In a day | 200 per form | 500 per form | 1,000 per key | 100 per link |

A workspace on Free can keep 1,000 tests and 100 MB. Paid plans can keep 5,000 tests and 500 MB. Past a
limit you get `TEST_LIMIT_REACHED` and nothing is stored. Old tests are never removed to make room.

## Turn local tests off

Owners and admins can turn this off on the form's **Tests** tab. Local addresses then get
`FORBIDDEN_ORIGIN`, like any other unlisted website.