2026년 HarmonyOS NEXT: React Native 마이그레이션 출시 전 검수 체크리스트
코드가 빌드되거나 화면이 열린다는 이유만으로 HarmonyOS NEXT 마이그레이션을 승인하지 말고, 대표 업무 흐름 하나를 시범 이관한 뒤 의존성·기능·실기기 회귀·배포와 롤백을 단계별로 확인해야 합니다. 이 기준은 기존 React Native 앱을 평가하거나 전환 중인 기업 기술 책임자와 엔지니어, 출시 품질을 맡은 테스트팀에 적합합니다.
기술 책임자는 시범 범위와 중단 조건을 정하고, RN·ArkTS 통합 담당자는 의존성과 인터페이스를 검증해야 합니다. 테스트 책임자는 목표 기기에서 재현 가능한 검수 증거를 남겨야 합니다.
마지막 갱신: 2026년 9월 29일. OpenHarmony의 ArkTS 및 UI 테스트 문서, React Native 커뮤니티 분기의 개발 문서와 버전 안내를 기준으로 검수 항목을 정리했습니다. 이 자료들은 HarmonyOS NEXT의 상용 출시 일정이나 개별 RN 의존성의 호환성을 보증하지 않습니다.
시범 이관은 대표 업무 흐름과 중단 조건부터 정합니다
시범 대상은 단순한 화면보다 실제 사용자가 완료해야 하는 업무 흐름으로 잡습니다. 로그인 이후 데이터를 불러오고, 수정 내용을 저장한 다음 다른 화면으로 이동하는 흐름처럼 RN 모듈과 네이티브 호출이 함께 작동하는 경로가 적합합니다. 권한 요청이나 오류 복구가 중요하다면 같은 경로 안에 포함합니다.
테스트 전에 지원 대상 기기와 시스템 버전을 기록합니다. 목표 환경이 정해지지 않으면 결과가 어느 배포 범위에 적용되는지 판단하기 어렵습니다. 공개 문서는 개발 언어와 테스트 기능을 설명하는 자료이지, 모든 상용 기기에서의 실행 결과나 RN 분기의 지원 약속은 아닙니다. ArkTS 개발 안내와 커뮤니티 분기의 개발 문서를 참고하되, 실제 프로젝트 결과를 별도로 확인해야 합니다.
| 시범 범위 | 통과 판단에 필요한 근거 | 실패 시 결정 |
|---|---|---|
| 로그인부터 핵심 작업 완료까지 | 단계별 기대 결과, 실행 로그, 재현 절차 | 인증 또는 업무 처리가 막히면 범위를 확대하지 않음 |
| 네이티브 기능과 권한 사용 | 호출 결과, 권한 허용·거부 시 동작 기록 | 지원 근거가 없으면 추가 검증 또는 대체 검토 |
| 오류와 복구 경로 | 오류 조건, 사용자 안내, 재시도 결과 | 복구 불가 결함은 출시 차단 항목으로 등록 |
통과·보류·중단 조건은 플랫폼의 강제 기준이라고 표현하지 말고 프로젝트 검수 기준으로 명시합니다. 예를 들어 핵심 업무 흐름이 끝까지 재현되지 않거나 필수 의존성의 실행 근거가 없으면 시범 이관을 보류하고, 그동안 다른 업무 영역으로 전환을 확대하지 않는 방식입니다.
의존성 검수에서는 빌드 성공과 실행 호환성을 분리합니다
React Native OpenHarmony 호환성은 패키지가 설치되거나 변환 코드가 생성되는지만으로 판단할 수 없습니다. 기존 앱의 네이티브 모듈, 서드파티 라이브러리, 빌드 스크립트, 서명, 런타임 호출을 항목별로 확인해야 합니다. 특히 플랫폼별 코드와 연결되는 모듈은 목표 분기와 버전의 안내를 읽고, 실제 프로젝트에서 재현 가능한 결과를 남깁니다.
| 점검 대상 | 확인할 자료 | 검수 상태 기록 |
|---|---|---|
| RN 커뮤니티 분기 | 개발 안내와 적용 대상 버전 | 확인 완료 또는 문서 근거 부족 |
| 서드파티 라이브러리 | 플랫폼별 적용 안내와 사용 조건 | 통과, 추가 검증, 대체 후보 |
| 빌드·서명·런타임 | 재현 절차, 오류 로그, 산출물 정보 | 재현 가능 여부와 담당자 |
커뮤니티의 버전 안내와 서드파티 라이브러리 적용 문서는 점검 근거로 활용할 수 있습니다. 다만 목록에 이름이 있거나 문서가 존재한다는 사실만으로 해당 앱의 구성과 사용 방식까지 검증된 것은 아닙니다. 문서와 실제 적용 조건이 맞지 않으면 상태를 ‘통과’가 아니라 ‘추가 확인’으로 기록합니다.
RN의 자바스크립트 실행과 UI 갱신은 같은 작업으로 취급할 수 없습니다. 앱의 통신 경로와 호스트 측 구현이 바뀌면 기존 동작을 그대로 가정하지 말고, 호출 결과와 화면 반영을 각각 확인합니다.
ArkTS 애플리케이션 테스트는 바뀐 화면과 기능의 검증 기록을 남기는 과정입니다. ArkTS 코드로 옮겼다는 사실 자체는 동작이 동등하다는 증거가 아닙니다. 팀에서 바꿔야 할 RN 동작과 호스트 측 또는 ArkTS 측에서 다시 구현할 부분을 구분하고, 담당자와 확인 결과를 연결해 둡니다.
핵심 흐름은 기대 결과와 재현 가능한 증거로 비교합니다
기능 검수는 이전 앱과 이관 앱에서 같은 입력과 조건으로 실행합니다. 로그인 결과, 서버 데이터의 읽기와 쓰기, 페이지 이동, 권한 허용·거부, 네트워크 오류 이후의 복구처럼 업무에 영향을 주는 동작을 우선합니다. 각 테스트에는 사전 조건, 실행 순서, 기대 결과, 실제 결과와 로그 위치를 기록합니다.
- [ ] 목표 기기와 시스템 버전을 테스트 기록에 적습니다.
- [ ] 로그인 성공과 실패, 세션 만료 시의 처리 결과를 남깁니다.
- [ ] 데이터 읽기·쓰기 이후 서버와 화면의 값이 일치하는지 확인합니다.
- [ ] 화면 이동과 뒤로 가기, 권한 허용·거부를 각각 시험합니다.
- [ ] 오류를 재현하는 입력과 로그, 수정 담당자를 결함 항목에 연결합니다.
- [ ] RN에서 유지되지 않는 동작은 ArkTS 또는 호스트 측 재구현 여부를 기록합니다.
공식 ArkTS 개발 안내는 언어와 개발 흐름을 살피는 자료입니다. 실제 앱에서 어떤 업무 동작이 보장되는지 대신 확인해 주지는 않습니다. 검수 결과가 기대와 다르면 결함을 재현 가능한 상태로 남긴 뒤 수정 또는 재구현 여부를 결정해야 합니다.
실기기 회귀는 지원 범위와 사용 조건을 맞춰 진행합니다
기기 검수는 팀이 지원하기로 정한 범위에 따라 수행합니다. 로그인과 주요 업무 흐름뿐 아니라 백그라운드에서 돌아온 뒤의 상태, 네트워크 변경, 장시간 사용 뒤의 오류 여부도 확인합니다. 특정 환경에서 수행한 결과를 다른 기기나 시스템 버전의 보장으로 확대 해석하지 않습니다.
| 회귀 시나리오 | 기록할 증거 | 미확인 상태의 처리 |
|---|---|---|
| 실제 기기에서 핵심 흐름 실행 | 기기·시스템 정보, 실행 기록, 로그 | 해당 범위를 검증 미완료로 표시 |
| 백그라운드 복귀와 네트워크 변경 | 전후 상태, 재현 절차, 오류 기록 | 출시 검토 전 추가 회귀 수행 |
| UI 반응과 장시간 실행 | 같은 조건의 추적 자료 또는 측정 결과 | 측정 전에는 성능 통과로 판정하지 않음 |
UI 자동화는 반복 가능한 화면 상호작용을 확인하는 데 유용하지만, 실제 업무 데이터와 기기별 동작까지 대신 검증하지는 않습니다. OpenHarmony UI 테스트 안내의 적용 범위를 살피고 자동화 결과와 실기기 업무 검수 결과를 따로 보관합니다. 안정성 검증에는 공식 안정성 테스트 안내도 참고할 수 있습니다.
성능 수치가 없다면 임의의 프레임 수나 허용 시간을 합격 기준으로 만들지 않습니다. 같은 기기, 같은 시나리오, 같은 데이터 조건에서 추적한 자료가 있을 때만 비교 결론을 내립니다. 측정 전에는 “성능 확인 완료” 대신 “측정 대기”라고 남깁니다.
출시 후보는 산출물과 롤백 책임까지 추적합니다
출시 직전에는 자동화·수동 회귀 결과, 남은 결함, 빌드 산출물, 서명 정보와 배포 설정을 서로 연결합니다. 서명 절차는 공식 앱 패키지 서명 도구 안내를 참고하고, 패키징 오류는 앱 패키지 관련 공통 문제 문서와 대조할 수 있습니다. 문서에 적힌 절차를 따랐다는 사실과 출시 산출물의 검증 완료는 별개이므로 결과물을 직접 확인합니다.
- [ ] 필수 의존성의 검증 상태와 미해결 결함을 확인합니다.
- [ ] 핵심 흐름의 자동화·수동 회귀 기록을 함께 보관합니다.
- [ ] 출시 후보 산출물과 서명·배포 설정을 식별할 수 있게 기록합니다.
- [ ] 중단 권한을 가진 책임자와 수정 담당자를 지정합니다.
- [ ] 롤백 대상 버전, 실행 절차와 복귀 후 확인 항목을 문서화합니다.
필수 의존성이 작동하지 않거나 핵심 흐름이 차단되면 출시를 보류합니다. 지원 대상으로 정한 기기의 회귀가 끝나지 않은 경우에도 검수 완료로 표시하지 않습니다. 무엇을 배포 차단 조건으로 삼을지는 프로젝트가 결정할 사항이며, 팀의 권고 기준을 플랫폼의 강제 요구사항처럼 표현해서는 안 됩니다.
자주 묻는 검수 판단을 정리합니다
React Native 앱은 빌드만 성공하면 마이그레이션이 끝난 것인가요?
아닙니다. 빌드는 구성과 컴파일 과정의 결과일 뿐, 실제 기기에서 네이티브 호출과 권한 처리, 데이터 변경까지 정상 동작한다는 의미는 아닙니다. 대표 업무 흐름을 실행하고, 실패 경로와 복구 결과를 기록해야 합니다. 기능 검수나 실기기 회귀가 남아 있다면 완료가 아니라 검증 진행 중으로 관리합니다.
의존성 문서에 지원 라이브러리로 나오면 바로 통과시켜도 되나요?
문서는 조사 출발점으로 사용하고, 프로젝트에서 실제로 쓰는 버전과 기능이 안내된 적용 조건에 맞는지 확인해야 합니다. 빌드와 실행 결과도 별도로 기록합니다. 문서의 지원 범위가 다르거나 재현 가능한 결과가 없다면 추가 검증 또는 교체 대상으로 남깁니다. 확인되지 않은 라이브러리가 핵심 흐름을 막는다면 이관 확대와 출시 판단을 보류합니다.
어떤 기기에서 출시 검수를 해야 하나요?
먼저 제품이 지원할 기기와 시스템 버전을 프로젝트에서 정하고, 그 범위 안에서 핵심 업무와 복귀·네트워크 변경 시나리오를 실행합니다. 테스트한 기기와 환경을 기록하면 결과의 적용 범위를 오해할 가능성이 줄어듭니다. 지원 목록에 포함된 환경의 검수가 완료되지 않았을 때는 해당 검증을 끝내기 전까지 출시 승인 근거로 삼지 않습니다.
시범 이관이 실패하면 다른 화면의 전환도 계속해도 되나요?
핵심 흐름을 막는 의존성이나 재현 가능한 기능 문제가 원인이라면 확대 작업을 멈추는 편이 안전합니다. 먼저 실패 조건과 영향 범위를 기록하고, 라이브러리 대체 또는 ArkTS·호스트 측 재구현이 필요한지 결정합니다. 수정 후 같은 조건으로 다시 시험해 결과를 확인한 다음에만 시범 범위를 넓힙니다. 실패 원인이 해결되지 않은 상태에서 전환량만 늘리면 검수해야 할 범위도 함께 커집니다.
이미 보유한 기기와 빌드 환경으로 반복 검수가 가능하다면 원격 자원을 추가하지 않아도 됩니다. 반대로 로컬 기기나 개발 자원이 부족해 빌드 일정과 회귀 계획이 지연된다면, 원격 개발 환경의 접근 방식과 운영 조건을 KuzCloud 도움말에서 먼저 확인할 수 있습니다. 원격 Mac은 빌드와 협업 자원을 보완하는 선택지이지, HarmonyOS NEXT 호환성이나 실제 목표 기기 검수를 대신하지는 않습니다. 기존 환경의 자원 부족과 운영 부담을 줄일 필요가 있을 때만 KuzCloud 콘솔에서 원격 Mac 이용 가능성을 검토하고, 플랫폼별 빌드 요구사항은 별도 실증 결과로 판단합니다.
출시 전 검수에 필요한 원격 맥 환경을 마련하세요
KuzCloud의 전용 맥 미니로 앱 빌드와 자동화 작업을 진행하세요.
물리 장비를 단독으로 사용하고 필요한 개발 도구를 자유롭게 구성하세요.