2026 HarmonyOS NEXT: React Native Migration Pre-Launch Acceptance Checklist
A React Native app compiles and opens, but the team still cannot confirm whether its login, permissions, and data flows work on target devices.
Treat the migration as accepted only after a representative business journey passes dependency, functional, device, performance, and release checks; if a critical dependency or core flow fails, pause expansion and resolve or roll back rather than treating conversion as proof of compatibility.
This checklist is for technical leads defining pilot scope and stop conditions, engineers integrating React Native with ArkTS, and test leads assembling release evidence. It is not a beginner migration tutorial or a guide to diagnosing one particular rendering issue.
Last updated September 29, 2026. Verification basis: the linked OpenHarmony ArkTS and UI-testing documentation, plus the React Native for HarmonyOS community branch README, release notes, and library-adaptation directory. These sources describe development and testing resources; they do not confirm a HarmonyOS NEXT commercial-release schedule or guarantee that a community branch supports any specific app.
Set the pilot boundary before changing the app
Choose a journey that represents real product risk, not the smallest screen that happens to launch. A useful pilot crosses the interfaces the production app depends on: for example, authentication, a server-backed read, a user action that writes data, navigation to a second screen, and a permission-dependent function. If no single journey covers the riskiest dependencies, define a second bounded journey rather than quietly expanding the pilot into a partial rewrite.
Record the starting point so that the team can reproduce the same test later:
- [ ] Name the pilot journey, its owner, the environments it uses, and the business outcome that counts as success.
- [ ] Record the React Native release, the exact React Native for HarmonyOS branch or commit, the build tools, and the dependency-lock state.
- [ ] Identify the actual target devices and HarmonyOS NEXT system builds included in the test. Do not infer device or system coverage from the fact that a development machine can compile the project.
- [ ] Define what permits the pilot to continue, what pauses additional migration work, and who can approve a scope change.
- [ ] Preserve a runnable baseline of the existing app and a test account or data set that can be used for comparison.
What belongs in a React Native migration pilot? Include at least one end-to-end business journey with meaningful native integration. A sample screen can confirm that the application starts, but it cannot establish whether authentication, storage, permissions, navigation, or error handling work together.
Make the decision criteria project-owned and explicit. A team can decide, for example, that a blocked payment or sign-in journey pauses expansion; that is a release policy, not an OpenHarmony platform rule. Keep those categories separate in the test plan. OpenHarmony’s ArkTS development guide documents the development model, but it does not set the project’s business acceptance thresholds.
Verify the branch and dependencies before integration
A compiled build is evidence of a build result, not evidence that every package behaves correctly on the target platform. Inventory dependencies by function, then assign each one a status: supported with reproducible evidence, waiting for verification, replaceable, or blocked. Include transitive packages and project-specific native modules; teams often find the unowned integration risk in those areas rather than in the visible screen code.
How should third-party dependencies be accepted after an RN-to-ArkTS migration? Require platform-specific adaptation evidence or a reproducible test of the exact package version used by the app. A library catalog entry is a lead for investigation, not a substitute for validating the team’s version, configuration, and use case.
For each dependency, retain:
- [ ] Package name, pinned version, direct or transitive status, and the feature that uses it.
- [ ] The source of any claimed HarmonyOS or OpenHarmony adaptation, including its branch, release notes, and known limitations.
- [ ] A minimal reproduction or application-level test that exercises the package’s actual use, including failure and permission-denied behavior where relevant.
- [ ] A disposition: keep, replace, wrap behind a platform interface, reimplement in ArkTS or the host layer, or block the pilot.
- [ ] The engineer responsible for closing the item and the evidence needed to change its status.
The React Native for HarmonyOS documentation lists a community branch and its development material. Its release notes include the branch identifier 0.72.5-ohos-5.0-release, which identifies a React Native version and an OpenHarmony release line for that branch; it is not a general compatibility guarantee for other branches, libraries, devices, or HarmonyOS NEXT builds. Check the community development documentation and the branch-specific release notes against the exact branch under test. For third-party packages, consult the community library adaptation directory, then reproduce the app’s own required behavior.
The branch identifier is a useful version-specific reference, not a promise that the app’s dependency tree is covered. A package listed as adapted may still have constraints around a particular release, API, permission, or usage pattern. If evidence does not cover the pinned package version and the production path, leave it marked “waiting for verification”; do not upgrade that status merely because the app builds.
Also inspect build scripts, environment variables, native modules, runtime permissions, signing inputs, and generated package contents. Keep the build command and its inputs under version control or in a traceable build record. Where signing is part of the release path, compare the produced artifact with the team’s signing procedure and the official HAP signing tool documentation. If packaging or installation fails, use the official application-package troubleshooting guidance to classify the issue before treating it as a migration defect.
A “green build” should close only the build task. It should not automatically close dependency compatibility, runtime behavior, or release readiness.
Prove one complete business journey
Once the dependency inventory has no unresolved blocker for the pilot path, compare the existing app and the candidate build through equivalent test cases. The goal is not to preserve every implementation detail. It is to show that each user-visible contract still works, or to document a deliberate replacement in ArkTS or the host layer.
- [ ] Authentication: test successful sign-in, invalid credentials, expired sessions, and the app’s expected response when authentication services cannot be reached.
- [ ] Data reads and writes: verify the displayed data, the result of a user change, persistence after navigation or relaunch where required, and error handling for failed requests.
- [ ] Navigation: cover forward and back transitions, deep links if the product relies on them, and state preservation when a user returns to a prior screen.
- [ ] Permissions: test the normal grant path and a denial or revocation path. Confirm that the user receives an appropriate explanation instead of an unexplained failure.
- [ ] Failure and recovery: exercise at least one relevant timeout, service error, or interrupted operation. Record what the user sees and whether retrying leaves the app in a consistent state.
For every case, retain the setup, steps, expected result, actual result, build identifier, device and system under test, logs, and a defect reproduction procedure. Screenshots can support a finding, but they usually cannot explain a failed network call, an incorrect state transition, or an exception. Attach relevant logs and traces where available, and avoid storing credentials or personal data in test evidence.
Which RN behaviors may need a new ArkTS or host implementation? Any behavior that relied on a native module, platform-specific permission flow, lifecycle callback, or bridge assumption should be reviewed rather than presumed portable. Record the old behavior, the new implementation boundary, and the test that demonstrates equivalence. The ArkTS guide explains the target development approach; the application team still needs to prove its own behavior on its chosen target.
A behavior difference is not automatically a release blocker if the product owner accepts it and the change is documented. An unexplained difference in a critical path is a blocker until the team either fixes it or makes an explicit product decision. This distinction prevents a migration review from confusing “not identical internally” with “not acceptable to users.”
Run device regression under recorded conditions
A simulator or development preview can help with iteration, but it cannot stand in for the actual supported device and system combinations in the release plan. Build the regression set from the product’s declared support scope. Record exactly which physical devices and system builds were tested, and mark everything else as unverified rather than implying broad coverage.
What should HarmonyOS NEXT release testing cover? At minimum, cover the pilot’s core business journeys on the target devices, plus the lifecycle and network conditions that could alter those journeys. Include app backgrounding and restoration, network loss and recovery, permission changes, and a sustained session appropriate to the product’s real use. The test plan should explain why each scenario matters to the app.
- [ ] Run the same scripted journey on each selected target device and save the result against its device and system identifiers.
- [ ] Background and restore the app at meaningful points, such as after sign-in or during a data workflow, and check whether state remains valid.
- [ ] Change network availability during a read or write, then verify whether the app recovers, retries safely, or reports an actionable failure.
- [ ] Exercise the long-running or repeated interaction patterns that matter to this product. Capture traces or other measurements under documented, repeatable conditions.
- [ ] Re-run affected journeys after a fix; attach the new evidence to the defect instead of replacing the original failure record.
Treat performance as a measured acceptance item, not an adjective. Record the device, system build, app build, data volume or test fixture, interaction sequence, measurement method, and trace. Compare candidate and baseline only when the conditions are sufficiently equivalent. If the team has not gathered that evidence, write “not measured” or “pending acceptance”; do not invent frame-rate, memory, launch-time, or stability claims.
OpenHarmony’s UI testing guidance describes the framework’s UI testing capabilities. The Wukong stability-testing guidance describes a separate stability-testing tool. These resources can inform test design, but automated interaction or stability checks do not prove that a real user can complete the product’s business workflow on every supported target. Keep automation results beside, not in place of, real-device business acceptance.
Assemble release-candidate evidence
Before approving a candidate, make the test record auditable by someone who did not run the migration. The record should connect the source revision and dependency state to the build artifact, test results, known issues, and release configuration. If any element cannot be reproduced, identify the missing owner and treat it as an open release risk.
- [ ] Build provenance: retain the source revision, community branch or commit, dependency lock state, build inputs, build result, and artifact identifier.
- [ ] Functional coverage: link each critical journey to its test cases, device results, logs, and unresolved defects.
- [ ] Automation and manual testing: distinguish automated checks from manual scenarios and show which business risks still require hands-on verification.
- [ ] Known issues: describe user impact, affected journey, workaround if one exists, owner, and the decision-maker who accepted or rejected the risk.
- [ ] Release configuration: verify that signing and other release inputs match the intended candidate, and keep the resulting package traceable to its build record.
- [ ] Approval trail: record who approved the candidate, which evidence they reviewed, and what remains outside the tested scope.
ArkTS application testing should be described accurately in the report: name the tools and scenarios actually run, and state what they do not cover. The official UI testing guidance is useful for defining interaction checks, but it does not turn an automated pass into a platform endorsement or a substitute for the team’s business acceptance. Keep platform documentation, community-branch evidence, and project policy in separate fields so reviewers can see which source supports each decision.
Apply explicit pause, proceed, and rollback rules
Use a decision record that separates project gates from platform constraints. A team may require all critical journeys to pass before broadening the migration; that is a project rule. A platform document describing a supported development or testing capability is evidence about that capability, not an instruction that every product must adopt the team’s chosen gate.
What should stop when the pilot fails? Pause expansion to additional screens, dependency upgrades made only to force progress, and release-candidate approval for the affected scope. Keep investigation work that can isolate the problem, such as a minimal reproduction or a dependency replacement assessment. Resume only after the owner presents the missing evidence and the designated approver accepts the result.
- Proceed: the selected journey works on the declared target devices; required dependencies have evidence for the pinned versions and use cases; critical defects are closed or formally accepted; and the artifact and test record are traceable.
- Pause: a critical dependency has no credible adaptation evidence, a core journey is blocked, device coverage is incomplete for the release claim, or a required performance result has not been measured.
- Roll back or return to the previous release path: the candidate causes an unacceptable production risk, the rollback artifact cannot be identified, or the team cannot restore the known-good release through its documented deployment process.
Before the first production decision, name the rollback owner, identify the known-good application version and its artifact, document the deployment or distribution steps, and specify how the team will verify recovery. Confirm that the relevant people can access the artifacts and records; a rollback plan that exists only in a ticket without an available build is not operational evidence. The precise approval threshold belongs to the project and its release governance. Do not present it as a HarmonyOS NEXT requirement unless an official platform source explicitly says so.
If the test team lacks enough local Mac capacity for its planned development or build workload, remote Mac resources may be one part of the workstation plan, not a substitute for target HarmonyOS devices or proof of React Native compatibility. Check whether the required tools and workflow are supported before moving any build step. KuzCloud’s remote environment console and service help information can help teams assess access and operating requirements; teams with sufficient local hardware or a requirement for direct physical-device access may be better served by keeping those tasks on site. Use the remote option only where it fills a verified resource gap, and keep the final HarmonyOS NEXT release decision tied to reproducible builds and actual target-device evidence.
Run Your Final Checks on a Dedicated Cloud Mac
Use KuzCloud to run release builds and regression checks on dedicated bare-metal Mac hardware.
Connect over SSH or VNC and install the tools your validation workflow requires.