Appearance
Testing and Logs
Testing and Logs helps you verify Cloud Flow behavior during development and investigate backend activity after publishing.
Cloud Flow runs on the server, so a Page or external caller may only see the final response—not the steps that produced it. Use the Cloud Flow test runtime, Logs, and the actual calling workflow together to determine whether a module ran, what it attempted, and whether it completed successfully.
This page focuses on testing and diagnosing Cloud Flow. For creating modules and configuring the test runtime controls, see Managing Cloud Flow. For exact logging and runtime API signatures, see the Server API.
A Typical Testing Workflow
A practical development sequence is:
- Save the Cloud Flow modules you want to test, including any shared Background Tasks.
- Choose the intended development path. Opening a Page or Form in Preview automatically starts the Cloud Flow development test runtime when needed. For testing Cloud Flow independently, open Backend → Cloud Flow and choose Start Test.
- Invoke the workflow through its intended caller: a Page in Preview, a Web Hook test URL, or logic implemented inside a Background Task.
- Confirm the observable result: a response, Database change, generated file, shared helper behavior, or other intended outcome.
- Open Logs and review the relevant test activity.
- Correct the module or its caller, save, and repeat the test, including failure cases.
- Choose Stop Test when you want to end the development test runtime explicitly.
- When the complete workflow is ready, use Publish Project, then verify the published behavior and review live logs where appropriate.
Save, Preview, Start Test, and Publish Project are different actions. Saving changes the development version; Preview exercises saved frontend behavior and starts the test runtime when needed; Start Test makes the runtime available for independent Cloud Flow testing; publishing releases Project changes to the published application.
Cloud Flow Test Controls
The Cloud Flow toolbar provides these controls:
| Control | Purpose |
|---|---|
| Start Test | Starts the Cloud Flow development test runtime when testing backend behavior independently of a Page or Form Preview. |
| Stop Test | Stops the Cloud Flow development test runtime explicitly. |
| Logs | Opens Cloud Flow logs for inspecting backend activity. |
Opening a Page or Form in Preview checks the Cloud Flow development test runtime and starts it when it is not already running. You do not need to choose Start Test before testing Cloud Flow through Preview. For more about frontend testing, see Previewing.
The development test runtime automatically stops two hours after it starts. Opening Preview again starts it when needed. Starting a new Preview does not restart an already-running runtime or extend its current two-hour period.
The test runtime is useful for Web Hooks, Background Tasks, and shared backend modules. The type of module determines what you should exercise while it is running.
A Background Task does not have a separate trigger or scheduling setting. Its own logic determines whether it initializes helpers, performs startup processing, or establishes a timer. Starting the test runtime is not equivalent to configuring or triggering a scheduled job.
For Background Task runtime behavior, see Background Tasks.
Test and Live Activity
Cloud Flow logs distinguish test and live activity. Use the appropriate log view when diagnosing a workflow.
| Context | What to Review |
|---|---|
| Test | Activity generated while developing and invoking Cloud Flow through its test runtime or development test path. |
| Live | Activity generated by the published Project and its published backend workflows. |
For example, a Web Hook may work when called from a Page in Preview but fail after publication because the published caller uses a different URL, the production data differs, or an external Connection is configured differently.
Keep the distinction between Cloud Flow runtime mode, Database environment, and external service environment clear. These are related, but they should not be treated as interchangeable.
Checking Test Mode in Code
The Server API provides $io.system.isTestMode() to identify whether the current Cloud Flow execution is in test mode:
js
if ($io.system.isTestMode()) {
// Development-only diagnostics or test-specific behavior.
}This is a runtime check, not a substitute for selecting appropriate Database data, protecting credentials, or configuring a provider's test mode. For exact behavior, see $io.system.isTestMode.
Opening and Reading Logs
In Backend → Cloud Flow, choose Logs to inspect backend activity.
Use the available test/live selection and search controls to narrow the entries you are investigating. Relevant log information can include:
| Information | What It Helps You Understand |
|---|---|
| Date and Time | When the activity occurred. |
| Test or Live | Which runtime context produced the entry. |
| Category | The kind of information being logged. |
| Level | A numeric logging level associated with the entry. |
| Message | The diagnostic information recorded by the workflow. |
| Related module or operation, where available | Which part of the backend behavior the message concerns. |
When investigating a failure, start from the time of the user action or external request. Review the relevant entries in sequence, then compare them with the response or visible behavior reported by the caller.
A missing expected log entry is a clue, not conclusive proof that a module never ran. The workflow may not have reached the logging step, the wrong test/live view may be selected, or the relevant messages may not have been recorded.
Logging from Cloud Flow
Useful diagnostic messages can be written from server-side logic using the documented $io.system.log API:
js
$io.system.log('Registration validation started', 'REGISTRATION', 1);
$io.system.log('Registration rejected: event at capacity', 'REGISTRATION', 2);The function signature is:
js
$io.system.log(message, category, level)messageis a string describing what happened.categoryis a string used to organize messages; choose meaningful values such asREGISTRATION,PAYMENT, orINTEGRATION.levelis a number. Use a consistent logging-level convention within the Project. The numbers in the example are illustrative, not predefined severity mappings.
The Server API documents the timestamped logging behavior and arguments. For the authoritative definition, see $io.system.log.
What to Log
Log meaningful milestones and outcomes rather than every intermediate value:
- The start of an important processing step.
- A validation or authorization decision, without exposing sensitive input.
- The result of a Database or file operation.
- An external service failure, identified by a safe status or error category.
- The point at which a Web Hook is preparing its response.
- A Background Task initialization, timer-driven action, or shared-helper failure.
For repeated or asynchronous workflows, a non-sensitive request or operation identifier can help connect related messages. Use identifiers that are appropriate to include in logs.
Logging Safely
Do not log API keys, OAuth tokens, passwords, private credentials, full sensitive records, raw file contents, or unredacted provider responses containing private information.
Prefer messages such as Order update rejected: permission check failed over logging the complete request payload. Logs support diagnosis; they are not a replacement for durable audit records or protected application data storage.
Testing Web Hooks
Test a Web Hook through the same kind of caller that will use it after publication. A Web Hook called from Page Flow and one called by an external service may need different tests.
Web Hooks Called from Pages
- Save the Web Hook and any required shared modules.
- Open the calling Page in Preview. Preview starts the Cloud Flow development test runtime when needed.
- Perform the action that invokes the Web Hook.
- Confirm that the Page handles success and error outcomes correctly.
- Open Logs and inspect the test activity.
- Verify the intended Database, file, or other backend result.
If the Page uses a modal Form, test the complete path: opening the Form, passing context, validating and submitting data, receiving the Web Hook result, and updating the opening Page.
Web Hooks Called Externally
- Open the Web Hook settings and use the development test URL displayed by ioLoop.
- Send a representative request using the configured Hook HTTP Method.
- Include the expected body, query parameters, headers, and authentication information where applicable.
- Check the HTTP status, response headers, body, and completion behavior.
- Review Logs and the actual backend effects.
- Repeat with missing, invalid, unauthorized, and duplicate requests.
Use the URL shown in the Project Editor rather than constructing it from an assumed URL format. After publishing, verify the corresponding published URL and its intended callers separately.
When an external caller should act as a Project User, include that user's Web Hook Key in the HTTP Authorization header:
http
Authorization: Bearer PROJECT_USER_WEB_HOOK_KEYTest at least these cases:
- A valid key for an active user permitted by the Web Hook's access configuration.
- A valid key for a user whose membership does not permit access and who does not have applicable Admin access.
- A missing or invalid key.
- A key associated with a non-active user.
- Valid authentication followed by an operation-specific authorization failure, such as requesting another user's protected record.
- A replaced key, confirming that the previous key is no longer accepted before considering rotation complete.
Do not include Web Hook Keys in Cloud Flow logs, test notes, screenshots, or saved example payloads. For the request format and security guidance, see Web Hooks — Calling as a Project User.
Responses and Errors
A Web Hook's HTTP response status is distinct from an application-level Result Object such as one containing status, data, or err.
When testing, verify both layers if the workflow uses them. A transport-level response alone does not prove that the intended application operation succeeded. The caller should not report success until its expected success conditions are met.
For detailed Web Hook configuration and response handling, see Web Hooks.
Testing Background Tasks
Background Tasks run according to their own logic. Test what each task actually implements, rather than looking for a separate schedule or trigger setting.
| Task Pattern | What to Verify |
|---|---|
| Initialization logic | The intended startup work runs and handles errors. |
| Shared helper module | Flow Share exports become available to dependent modules. |
| Timer-driven task | The timer is established and the work executes under the intended conditions. |
| Data-processing task | Records or files are processed correctly, including empty and failed operations. |
Start the test runtime and check logs and results. If a task establishes a timer, verify what happens after the runtime is stopped and restarted. Runtime-only state and timers do not serve as durable progress records.
For repeated work, test overlapping calls, retries, restarts, and duplicate processing. A successful Database operation followed by a failed external service call can create a partial outcome that needs explicit recovery handling.
For more detail, see Background Tasks.
Testing Flow Share and Module Dependencies
Shared backend functions and values are commonly exported by Background Tasks and consumed by Web Hooks or AI Agent modules.
When a shared helper is missing or behaves unexpectedly:
- Confirm the providing module is enabled and saved.
- Check that it publishes the expected Flow Share name.
- Check module Load Order; providers should load before consumers that need them.
- Confirm that any asynchronous initialization has completed before the helper is used.
- Test the consuming module through its real invocation path.
- Restart the test runtime when you need to verify initialization behavior from a fresh runtime.
Load order establishes initialization order, not completion of asynchronous work. Flow Share is runtime-only and must be recreated when the runtime starts again.
For details, see Flow Share.
Database, Files, and External Connections During Testing
Cloud Flow testing may read or change Project data, generate files, or call connected external services. Test these operations deliberately.
During Page Preview, built-in Database operations automatically use the Project's development database. Reads, creates, updates, and deletes through the built-in Database capability do not target the production database in that Preview context.
When testing a Cloud Flow module directly through the development test runtime or an external test caller, confirm the intended execution context and use representative development records. Do not assume a custom external call or separately configured connection automatically follows the same environment behavior.
| Operation | Testing Consideration |
|---|---|
| Database | Use development records and verify actual changes, not only returned messages. |
| Named Queries | Check query inputs, access behavior, empty results, and expected fields. |
| File operations | Inspect generated, uploaded, or deleted files and the permissions that apply. |
| Connections | Verify provider credentials and test/live mode; calls may have real external effects. |
| Payment or notification workflows | Avoid real charges, emails, or other consequential actions unless explicitly intended. |
Testing through the Cloud Flow runtime does not mean that all external services are simulated. If a workflow sends messages, modifies a third-party system, or processes payments, choose safe provider settings and test inputs first.
For data-environment details, see Development and Production Data and Previewing.
Example: Diagnosing a Registration Web Hook
Consider a CreateRegistration Web Hook used by an event-registration Page. It checks event capacity, creates a registration when allowed, and returns a result.
1. Prepare the Test
Save the Page Flow, Web Hook, and any shared helpers. Prepare development records for an event with available capacity and an event that is full. Opening the registration Page in Preview starts the Cloud Flow development test runtime when needed.
2. Test a Successful Request
Open the registration Page in Preview and submit valid details. Verify that the Page displays the expected result and that a registration record was created in development data.
Inspect Logs for meaningful steps such as validation, capacity check, Database result, and response preparation, if the workflow logs them.
3. Test a Rejected Request
Submit for the full event. Confirm the Web Hook rejects the request, no registration is created, and the Page shows a useful message rather than a success confirmation.
4. Test Failures and Repeated Requests
Try missing values, invalid record IDs, unauthorized callers, a repeated submission, and a simulated or safely reproducible backend failure. Confirm that failed requests do not produce unintended records or external side effects.
5. Review and Publish
Review the responses, log entries, and development records. After the completed workflow is saved and published, verify the published Page and Web Hook separately using appropriate production-safe checks.
This example illustrates the diagnostic process, not a predefined Cloud Flow block sequence.
Test Cases to Include
| Test Case | What to Check |
|---|---|
| Success | The workflow performs its intended operation and returns the expected result. |
| Missing or invalid inputs | Inputs are rejected safely with helpful feedback. |
| Unauthorized caller | No protected data or operation is exposed. |
| Empty or missing records | The workflow handles absent data intentionally. |
| Repeated request | Retries and duplicates do not create unintended effects. |
| Concurrent work | Related processing does not conflict or exceed intended limits. |
| External failure | Connection errors are handled and reported appropriately. |
| Restart-sensitive behavior | Shared helpers, timers, and runtime-only state initialize correctly. |
| Test versus live | The correct endpoint, Database environment, and external provider settings are used. |
Troubleshooting Cloud Flow Failures
When a workflow behaves unexpectedly, trace it from the caller to Cloud Flow and back to the caller:
- Confirm the Cloud Flow module is enabled and its latest changes are saved.
- For development tests, confirm the test runtime is running where required.
- Check the caller's Web Hook URL, HTTP method, request data, and headers.
- Check Access (Security) and the authorization checks implemented by the workflow.
- Confirm the required tables, queries, files, Connections, and Flow Share values exist.
- Inspect the test or live Logs for the relevant execution.
- Check asynchronous completion and the success/failure handling of Database or external calls.
- Confirm that the Web Hook produced the expected HTTP response and application result.
- Verify how the Page Flow, custom frontend, or external caller handles that result.
| Symptom | What to Check First |
|---|---|
| No expected test activity | For Page-driven testing, open Preview again if the test runtime has stopped. For independent backend testing, choose Start Test. Then check enabled state, the correct endpoint, and the test/live log selection. |
| Web Hook cannot be reached | Development versus published URL, HTTP method, access configuration, and runtime availability. |
| Request data is missing | Request body, query parameters, headers, content type, and caller configuration. |
| Access denied | Web Hook access, verified identity, User Group membership, and record-specific rules. |
| Bearer request is denied | Authorization header format, Web Hook Key, associated user status, User Group membership, role level, and Web Hook Access (Security). |
| Database result is unexpected | Data environment, table, query inputs, named-query definition, and permissions. |
| External call fails | Connection setup, provider mode, credential availability, and safe error diagnostics. |
| Background Task does not run as intended | Initialization, task logic, timer setup, runtime state, and logs—not a scheduler setting. |
| Shared helper is unavailable | Flow Share name, provider module, load order, and initialization readiness. |
| Caller shows success after failure | HTTP response, Result Object, and the caller's success conditions. |
| Changes are missing from the published Project | Whether the updated modules and callers were saved and the Project was published. |
For Page-specific browser debugging, see Page Flow Previewing and Troubleshooting.
Good Practices
- Test through the real caller. Use Page Preview for Page-initiated Web Hooks and representative external requests for external Web Hooks.
- Keep test and live activity distinct. Confirm the runtime and log context before diagnosing results.
- Use structured, purposeful logs. Record meaningful steps, categories, and outcomes without leaking data.
- Check side effects. Confirm Database records, files, and external results rather than trusting a success message alone.
- Test denied and failed paths. Authorization failures, empty results, and external errors deserve as much attention as success.
- Make repeated work safe. Plan for retries, duplicate Web Hook calls, timer overlap, and runtime restarts.
- Review dependency initialization. Shared providers should be ready before dependent modules use them.
- Use safe test Connections. Test runtime mode does not automatically change the behavior of external providers.
- Verify after publishing. Check published callers and live logs after releasing changes.
Common Mistakes
Avoid these patterns:
- Testing a Cloud Flow module only by saving it, without invoking its real behavior.
- Forgetting to choose Start Test when testing Cloud Flow independently of a Page or Form Preview.
- Assuming a Background Task has a configurable schedule or external trigger setting.
- Treating a missing log message as definitive proof that a Web Hook was never called.
- Logging complete payloads, credentials, private records, or unredacted external responses.
- Testing only as Admin or only with one ideal data record.
- Assuming every Connection uses test mode while Cloud Flow is being tested.
- Confusing the Web Hook's HTTP status with the application-level result.
- Forgetting to test retries, duplicate submissions, and Background Task restarts.
- Assuming saved development changes are already published.
Testing and Logs are most effective when used together: start the appropriate runtime, exercise the real workflow, inspect the response and side effects, then use logs to locate and explain failures.