Local testing

The OCP local testing tool provides a complete local development environment for building, testing, and debugging your OCP applications before publishing them to Optimizely Connect Platform (OCP).

You can get the following benefits by using the OCP local testing tool:

• Faster development – Test changes instantly without deploying to the cloud.
• Easy deployment – Deploy changes to the cloud from within the testing tool.
• Full settings form support – Preview and test your app's settings form as it displays in the OCP App Directory.
• App directory – Access the app directory for validation, conditional fields, and dynamic data sources.
• Real-time reloading – Automatically detect and rebuild code changes.
• Interactive testing – Test functions, jobs, and lifecycle hooks through a web interface.
• Detailed logging – View comprehensive logs for debugging.

Prerequisites

• Access to OCP app.
• A working OCP CLI installation.

Launch the testing tool

1. Go to your App Directory containing the following app.yml:

   Bash

   cd my-ocp-app

2. Start the local testing tool using OCP CLI:

   Bash

   # Using OCP CLI
   ocp dev

3. Access http://localhost:3000 in your browser, which automatically opens after you start the local testing tool.

4. Ensure automatic rebuilds are working. The testing tool detects file changes in your app's src/ folder and rebuilds automatically.

5. Test your changes in the web UI.

6. Review logs in the console panel if issues occur.

Understand the web interface

The local testing tool provides a web-based interface with the following sections:

• App Settings – Configure and preview your app's settings form.
• Functions – Test webhook and HTTP functions with custom payloads.
• Jobs – Run jobs manually and view execution history.
• Destinations – Test data sync destination configurations.
• Sources – View source schemas.
• Opal Tools – Test HTTP tool calls with custom payloads.
• Console – View logs from your app. You can filter by source, level, and category.
• Settings – View and edit your app-stored storage.
• Secrets – View and edit your encrypted data.
• KV Store – Access your key-value data.
• Shared KV – Access your shared key-value data.
• Notifications – View your app notifications.
• Environment – View environment variables available to your app.
• Deploy – View app deployment status.

Configure the tool

Configuration file

Create a .ocp-local/config.json file in your app directory for advanced configuration. The account configuration populates the account object in the AppContext available to your app code.

{
  "account": {
    "organizationId": "my-org-123",
    "instanceId": "my-instance-456",
    "trackerId": "my-tracker-id"
  }
}

📘

Note

You should add the .ocp-local folder to your .gitignore file to avoid accidentally committing configuration data to your git repository.

Publishing to OCP

After testing your app in the local testing tool, deploy your app to OCP. This can either be done using the OCP CLI or from within the local testing tool using Deploy.

📘

Note

Local testing simulates the OCP environment but cannot replicate all production behaviors. Test your app on a development OCP account before releasing. See Feature comparison for details on what must be tested after publishing to OCP.

Feature comparison

This section compares the features supported by the local testing tool with those that can only be tested after publishing your app to OCP.

Quick reference

Lifecycle hooks

Workarounds:

• OAuth testing – Test OAuth logic in isolation using unit tests. Mock the authorization flow responses.
• Upgrade testing – Use onUpgrade() to test migration logic. onFinalizeUpgrade and onAfterUpgrade must be tested in staging.

Test locally

Test the following features in the OCP local testing tool:

• Settings forms and App Directory UI
• Function HTTP request and response handling
• Opal Tools request and response handling
• Basic lifecycle hooks like install, uninstall, or settings forms
• Job logic and state management
• Destination ready or deliver
• View source schema definitions
• All storage operations like KV Store, Settings, Secrets
• Notifications and logging

Test after publishing to OCP

Test the following features after publishing:

• OAuth flows (onAuthorizationRequest and onAuthorizationGrant)
• Full upgrade lifecycle (onFinalizeUpgrade and onAfterUpgrade)
• Cron-scheduled jobs
• Channel operations (all methods)
• Liquid extensions
• Production-like performance and scaling