# Debugging, tests and profiling

[Programming guides](README.md) · [Editions](editions.md)

Creator Pro, including its technical trial, adds a debugger, a fixture test runner and a source profiler in the desktop IDE and CLI. Basic **Step**, inspection, ordinary error messages and manual testing remain free in Learner. These tools do not add Pro requirements to ordinary Core source.

## Debug a program

Open **Development tools · Pro** in the IDE. Enter executable line numbers separated by commas for breakpoints, then start the debugger. It pauses before the first executable statement. Comments and blank lines are not breakpoint locations.

- **Step Into** reaches the next statement, including statements in a called function.
- **Step Over** completes the current statement, including its calls, branch or loop. An explicit breakpoint inside it still stops execution.
- **Step Out** finishes the current function call; it is unavailable in the outermost frame.
- **Continue** runs to the next breakpoint or completion.
- Select a call-stack frame to inspect its visible local variables. The innermost frame comes first.

Add a watch such as `score + 1` or `player["name"]` using the program's syntax language. Watches can read values and evaluate operators, indexing and members. They cannot call functions, assign values or request file/network access. An unsupported expression shows an error without modifying the program.

The CLI offers the same controls:

```sh
pliro debug --break 7 example.pliro
```

At its prompt, use `into`, `over`, `out`, `continue`, `stack`, `frame 0`, `watch score + 1`, `break 12`, `clear` or `stop`. Flags come before the file path. The CLI debugger and profiler cancel interactive program input; use the IDE when debugging forms and questions.

Changing source starts a new execution. Stop closes the session and its granted resources. Advanced application access still requires [separate declarations and permissions](advanced-applications.md).

## Run repeatable tests

A test suite is a UTF-8 JSON file. Save this as `suite.json`:

```json
{
  "schemaVersion": 1,
  "cases": [{
    "name": "double",
    "locale": "en",
    "source": "function double(x):\n    return x * 2\nlet answer = double(4)\nsay answer\n",
    "expectedOutput": "8\n",
    "assertions": ["answer == 8"]
  }]
}
```

Run `pliro test suite.json`. The command writes a JSON report and exits with a nonzero status when a case fails. The IDE test panel accepts the same JSON; capture the current source as a starting case, edit it, run the suite or cancel it.

Each case specifies `name`, `locale` (`en` or `nl`), `source` and exact `expectedOutput`. Optional fields:

| Field | Meaning |
|---|---|
| `expectedState` | `finished` by default; use `failed` to expect a runtime failure |
| `assertions` | Read-only expressions that must each evaluate to true after execution |
| `modules` | Map from portable module filename to source text, for integration fixtures |
| `database` | `true` provides a fresh in-memory SQLite database for this case |

Variables, saved values and database state are isolated between cases. Test cases never inherit selected files, live network access, production secrets or interactive input. This supports repeatable unit and module/database integration tests; it is not a runner for arbitrary shell commands or live services.

Resource bounds are 128 cases, 127 modules and 64 assertions per case, 4096 bytes per assertion and 2 MiB total fixture text. Execution allows 100,000 instructions, 5 seconds and 64 KiB output per case, and 60 seconds per suite. These are safety limits, not commercial project or execution quotas.

## Find expensive statements

Run a profile from the IDE, or:

```sh
pliro profile example.pliro > profile.json
```

The CLI writes the report to standard output and program output to standard error. Each statement row identifies its source position, visit count and inclusive elapsed time in nanoseconds. The report also records evaluator visits and truncation.

Time spent paused in the debugger is excluded. Time spent waiting, performing I/O or running child statements is included. Nested rows overlap: do not add them together as total CPU time. This profiler measures source execution time; CPU sampling, allocation profiling and native-process debugging are not available.

## Keep your work

**Keep draft data** retains reports and suite text. With valid Learner access, losing Pro still lets you open, edit and save projects and retain collected reports; active Pro sessions stop. Generated applications have no Pliro licence check.

These development tools currently run in the desktop IDE and CLI. The public browser playground does not offer them. Production crash/logging tools and live-service test adapters remain planned.

[Advanced data and networking](advanced-applications.md) · [Finding mistakes](debugging.md)