Skip to main content

Testing your form

info

This content progresses from beginner to advanced Studio user knowledge.

Testing your form thoroughly before activation prevents errors from reaching your live application. Studio provides two environments for this purpose: Preview and Form playground.

Both render your form the way Form renderer does in production, but each serves a distinct purpose at different stages of development.

good to know

For a step-by-step beginner walkthrough of testing and activation together, see the Start here - Test and activate your form section.

Preview​

Preview is the quickest way to test the form you are currently editing. To start Preview:

  1. Go to Form builder.
  2. Open the form you want to test and preview.
  3. Click the Preview button in the editor toolbar to open the form in a new browser tab.

Any change you make in the editor is reflected in Preview in real time. There is no need to save or refresh.

The Preview screen is divided into four areas:

  • Left panel: Enter the form's main variable (EHR ID) to connect to a patient record. If an EHR ID is provided, you can save a composition and review previously saved compositions for that patient.
  • Right panel: Switch between screen sizes (desktop, tablet, mobile, custom), change the display language, adjust the date format, and modify other context parameters.
  • Toolbar: Validate the form, restore it to its defaults, or save a composition.
  • Canvas: The rendered form, exactly as it will appear in a live application.
good to know

EHR ID is the patient electronic healthcare record. For trial Studio users, you have available a couple virtual patients you can use here. Licensed users may have their own testing Studio environments with virtual patients available. You shouldn't be testing on real-life EHR IDs.

Form playground​

Form playground is a standalone testing environment, separate from the Form builder editor.

Use it when you want to:

  • Test a form without having it open in the editor
  • Select and compare specific form versions
  • Test a form built by a colleague
  • Run a structured quality check across multiple forms in a project

To use Form playground:

  1. Go to your selected project and open it.
  2. Click on Form playground from the available tool list.
  3. Use the selectors at the top of the screen to choose a form and a form version.
  4. The form renders below.

The same Preview controls are available: EHR ID input, language and date format settings, validate, and save.

Form playground and Preview share the same core rendering and validation functionality. The key difference is scope: Preview is locked to the form you are editing. Form playground gives you free selection across all forms and versions in your project.

Testing across multiple form versions​

Use Form playground's version selector to test a specific saved version of a form.

This is useful when:

  • A new version is in development and you want to compare it against the currently active version
  • You are investigating a regression introduced in a recent save
  • A stakeholder wants to review a specific historical version before sign-off

Select the version from the dropdown at the top of the Form Playground screen.

Testing strategy for complex forms​

Forms with multiple pages, conditional logic, or data-bound fields require a more structured approach. The following covers the most common scenarios.

Multi-page forms​

To test multi-page forms:

  1. Navigate through every page in sequence to confirm page transitions work as expected.
  2. Return to earlier pages and modify values to confirm that downstream pages update accordingly.
  3. Validate each page individually.
warning

The validate button checks only the currently visible page. There is no single-button option to validate all pages at once. A successful validation on one page says nothing about the validity of any other page. For forms with complex required-field rules or openEHR multiplicity constraints, understanding exactly what validation checks (and what it does not) is essential before activation. See the Validating your form section for more detail.

Conditional logic and dependencies​

To test conditional logic and dependencies:

  1. Test each condition by entering values that should trigger it. Confirm that the expected fields appear or are hidden.
  2. Enter values that should not trigger a condition and confirm the form remains in its default state.
  3. Test edge cases: Empty fields, boundary values for numeric ranges, and toggled boolean fields.
  4. Confirm that hidden fields do not block composition saving.

Data-bound fields​

To test data-bound fields:

  1. Enter a valid EHR ID in the left panel before testing data-bound fields.
  2. Verify that AQL-sourced dropdowns and list fields load the expected values from the EHR Server.
  3. If your form pre-fills from a composition, pass a composition ID and confirm that the saved values populate correctly.

Testing with different languages and date formats​

If your form supports multiple languages, test each language before activation.

In the right panel of Preview or Form playground:

  1. Select the target language from the language dropdown.
  2. Verify that all labels, helper text, and validation messages display in the selected language.
  3. Confirm that the date format changes correctly if the selected language or territory requires a different format.

To change the date format independently of language, adjust the date format setting in the right panel. The default format is dd/MM/yyyy.

good to know

Tip: Test language switching mid-session to confirm the form responds correctly and that no labels revert to their default values or display raw translation keys.

Context parameters​

Context parameters control how the form is rendered and how it behaves during testing or in a live application. In Preview and Form playground, they are available in the right panel under Context parameters. In Form renderer, they are set via the EhrFormContext object.

The parameters are grouped below by function.

Language and localisation​

Language (language: string)

Sets the display language for the entire form. If not set, the form uses the default language defined in its form definition. Use an ISO 639-1 language code (examples: 'en', 'fr', 'de').

Territory (territory: string, default: SI)

Provides the form with a territory code for locale-aware formatting. Use an ISO 3166 country code (examples: 'GB', 'FR'). Affects date and number formatting where locale conventions differ.

Date format (dateFormat: string, default: dd/MM/yyyy)

Sets the date display format for all DV_DATE and DV_DATE_TIME fields. Accepts date-fns v2 format tokens. Useful when your application uses a different date convention to the Studio default.

Time placeholder (timePlaceholder: MrdTimePlaceholderFormat)

Sets custom placeholders for hours and minutes on DV_TIME and DV_DATE_TIME fields.

Date placeholder (datePlaceholder: string)

Sets a custom placeholder for date fields. Priority order: Annotation-level placeholder → this context value → derived from date format.

Display date input mask (displayDateInputMask: boolean, default: false)

When enabled, the date field immediately shows the format mask (example: __-__-____) as the user focuses on it. The user only needs to type the numeric values — separators are inserted automatically.

Validation behaviour​

Validation disabled (validationDisabled: boolean, default: false)

Disables all client-side validation on the form. Useful for testing form structure without validation errors interfering, or for rendering a form in a read-only context where validation is not relevant.

Display validation messages on touched (displayValidationMessagesOnTouched: boolean, default: false)

By default, validation errors only appear when the user attempts to submit or validate the form. When this option is enabled, validation errors also appear as soon as a field is touched and then unfocused, even before a save attempt is made.

Show fields required indicator (showFieldsRequiredIndicator: boolean, default: false)

When enabled, required fields display a visual indicator (typically an asterisk or similar marker) to signal to users which fields must be completed.

Show numeric range placeholder (showNumericRangePlaceholder: boolean, default: false)

When enabled, numeric fields with defined min/max restrictions display a placeholder showing the allowed range (for example, "Insert value from 1 to 10"). Applies to DV_COUNT, DV_PROPORTION, and DV_QUANTITY fields that have range restrictions but no custom placeholder.

Form behaviour​

Readonly (readonly: boolean)

Renders the entire form and all its fields in a non-editable state. The form's original layout is preserved. Use this to display a form that users can view but not modify.

warning

Readonly preserves the form's layout. It is distinct from presentation mode, which reformats the form into a simplified name-value view.

Disable form script (disableFormScript: boolean, default: false)

Suppresses all dependencies and form script execution. The form renders in its base state with no conditional logic applied. Useful when testing layout or structure independently of dynamic behaviour, or for diagnosing issues caused by scripts.

Disable script run on initialisation (disableScriptRunOnInitialization: boolean, default: false)

Prevents the form script from running when the form first loads. Scripts will still run in response to subsequent user interactions. Use this when you need the form to render in its default state on load before any script logic is applied.

Textarea auto-size (textareaAutosize: boolean, default: false)

When enabled, text area fields expand vertically as the user types, rather than showing a scrollbar. Useful for forms where lengthy free-text responses are expected.

Composition and data​

Auto prefill (autoPrefill: object, default: { enabled: false, mode: 'LATEST_COMPOSITION' })

Automatically populates the form with values from an existing composition for the provided EHR ID. Three modes are available:

  • LATEST_COMPOSITION: Pre-fills from the most recent composition saved for the EHR ID, regardless of lifecycle status.
  • LATEST_COMPLETED_COMPOSITION: Pre-fills from the most recent composition with a completed lifecycle tag.
  • CUSTOM_AQL_VIEW: Pre-fills from a custom AQL view.

Requires a valid ehrId variable to be set in formEnvironment. Useful for follow-up forms or recurring data entry where previous values should carry forward.

When using CUSTOM_AQL_VIEW option, additional parameters can be provided to the Custom Aql view parameters text field.

Display​

Presentation mode (presentationMode: boolean, default: false)

Renders the form in a read-only, print-friendly view. All field values from the loaded composition are displayed in a simplified name-value format in a single column, regardless of the form's original multi-column layout.

Use presentation mode to display a completed and saved composition for review or printing — for example, in an audit context or when showing a patient their submitted data.

warning

Presentation mode requires a composition to be loaded. Without a composition, the form renders as empty in presentation mode.

Show all pages (showAllPages: boolean, default: false)

Displays all pages of a multi-page form simultaneously in a single scrollable view. Primarily used together with presentation mode to show a complete submission across all pages at once. Pages specifically excluded from multi-page display via the Pages panel are still excluded.

Dropdown presentation minimum items (dropdownPresentationMinItems: number)

When set to a number n ≥ 0, dropdown fields with n or fewer selectable options are automatically converted from a dropdown into radio buttons or checkboxes. This improves usability for fields with a small number of options.

Connectivity​

Terminology URL (terminologyUrl: string)

Overrides or supplements the terminology server URL defined in the form definition. Fields that use terminology binding will connect to this URL to retrieve coded values. Use this when deploying a form in an environment where the terminology server differs from the one configured in Studio.

CSP settings (cspSettings: { enabled: boolean, nonce?: string })

Configures Content Security Policy nonce behaviour for the renderer. See Security for details.

Frequently asked questions (FAQs)​

What is the difference between Preview, Form playground, and Form renderer?

Preview is scoped to the form you are currently editing and updates in real time. Form playground lets you select and test any form and version in your project independently of the editor. Form renderer is the JavaScript library you install into a clinical application to render forms for end users in production.

Do I need to test my form before activating it?

Testing is not enforced by Studio, but it is strongly recommended. Validating your form in Preview or Form playground before activation reduces the risk of publishing a form with errors to a live application.

Can I test a form without an EHR Server connection?

You can preview a form's layout and conditional logic without a live EHR Server connection. Saving compositions and testing data-bound fields require an active connection and a valid EHR ID.