Skip to content

Testing and Troubleshooting

Use this checklist after creating a form and after receiving core updates. Test with the same dataset or program metadata used by the tutorial.

1. Check the extension loads

  • [ ] Select the intended dataset or program and confirm the custom layout appears.
  • [ ] Open another dataset or program and confirm its expected layout still appears.
  • [ ] Reload the page and reopen the form.
  • [ ] Confirm there are no extension import or rendering errors.

2. Check values and validation

  • [ ] Existing values appear in the correct fields.
  • [ ] Required fields show clear validation feedback.
  • [ ] Numeric fields and option values match the metadata.
  • [ ] Saving and reopening restores the values entered.
  • [ ] Editing and clearing a value behave as documented.
  • [ ] A failed save does not display a success message.
  • [ ] Disabled, loading, completed, and read-only states behave as required by the workflow.

3. Check the form-specific workflow

Form type Verify
Aggregate Values belong to the correct dataset, organisation unit, period, and category context. Switching context shows the correct values.
Event Creating saves one event; editing updates that event. Required event dates and status are preserved.
Tracker Values belong to the correct tracked entity, enrollment, program stage, and event. Editing does not create duplicate records.

4. Troubleshoot common problems

Problem What to check
Custom form does not appear Confirm useExtensions.jsx runs, component imports resolve, the configuration shape matches the form type, and identifiers match the selected dataset or program.
Event form renders incorrectly event.forms[PROGRAM_UID] expects an object containing Form, rather than a component alone.
Tracker custom stage does not appear Check both the program identifier and stage identifier in tracker.programConfig.
Tracker list returns E1006 for the tracked entity type Check data sharing on the tracked entity type as well as the program. Metadata viewing alone does not grant access to client records. The guide package grants data capture on the demo type, program, and stages.
Existing values are missing Check data element or attribute identifiers and the selected data context. For aggregate forms, also check category combinations.
Option labels display but values fail validation Check stored option codes against the configured option set.
Save is blocked Check required fields, event dates, metadata validation, access, and any completion or locking state.
Save fails Inspect the returned error and the request context; confirm instance access and user permissions.
Values appear under the wrong context Check organisation unit and period for aggregate data, event identity for events, and entity, enrollment, stage, and event identity for tracker data.
Local connection or authentication fails Follow Start Locally troubleshooting.
A core update breaks the extension Compare the affected core interface with your extension and repeat the relevant form checks after adapting it.

5. Record and commit your extension

Keep the form purpose, dataset/program identifiers, setup instructions, field mapping, and testing results in your project repository. Record the core version or commit used for testing.

Follow Conventional Commits and Commitizen to review, stage, commit, and hand over your changes for the project's review process.

6. Test and release an installation package

Use Create a Local Installation ZIP to test the app inside DHIS2. Use Versioning and Releases when the reviewed project is ready for a versioned GitHub Release and installation package.

Repeat the relevant checks on the installed application, including saving and reopening data.

7. Maintain the form

Repeat the relevant checks after changes to core code, extensions, or DHIS2 metadata. An unchanged extension folder can still require compatibility changes when a core interface changes.