<p align="center">
<img width="180" src="https://raw.githubusercontent.com/NativeScript/SimDeck/HEAD/packages/client/public/simdeck.png">
<h1 align="center">SimDeck</h1>
<p align="center">
SimDeck은 에이전트를 사용하여 모바일 앱 개발을 간소화하기 위해 구축된 개발자 도구입니다.
가장 좋아하는 IDE 및 CLI에서 iOS 시뮬레이터와 Android 에뮬레이터를 구동할 수 있습니다.
</p>
</p>
<hr/>
Codex Screenshot
사용해 보기
선택한 IDE에서 해당 URL을 엽니다. 예를 들어, Codex의 인앱 브라우저를 사용할 수 있습니다.
에이전트 활용을 위해 CLI를 전역으로 설치합니다:
CLI 설치 후, 에이전트가 안정적인 SimDeck 워크플로우를 알 수 있도록 Codex 스킬을 설치합니다:
px skills add NativeScript/SimDeck --skill simdeck -g
VS Code의 경우, 편집기 내에서 시뮬레이터 뷰를 열려면 nativescript.simdeck-vscode 확장을 설치하세요.
기능 (Features)
- iOS 시뮬레이터와 Android 에뮬레이터 모두에 대한 네이티브 H.264 스트리밍 지원
simdeck CLI를 사용하여 private iOS accessibility API 및 Android UIAutomator를 이용한 전체 시뮬레이터 제어 및 검사 기능- 접근성 뷰 트리(accessibility view tree)를 사용한 실시간 화면
describe 명령어 제공 - 에이전트에게 적합하도록 토큰 효율적인 형식으로 제공
- 프로파일링 내장: CPU, 메모리, 디스크 쓰기, 네트워크 처리량, hang 신호 및 스택 샘플링
- 장치 베젤을 위한 CoreSimulator chrome 에셋 렌더링 지원
- 생성된 패턴, 로컬 미디어 파일 또는 스트림 URL, 또는 Mac 카메라 소스로부터의 iOS 시뮬레이터 카메라 시뮬레이션
- 앱의 뷰 계층 구조를 실시간으로 디버깅하기 위한 NativeScript, React Native, Flutter, UIKit 및 SwiftUI 런타임 인스펙터 플러그인
- 접근성 상태를 쿼리하고 시뮬레이터 제어를 구동할 수 있는 빠른 JS 기반 앱 테스트용
simdeck/test 기능
문서 (Documentation)
전체 문서는 simdeck.sh에서 확인할 수 있으며, 가이드, CLI 레퍼런스, REST API, 비디오 파이프라인 및 인스펙터 프로토콜을 포함합니다.
호스팅되는 풀 리퀘스트 시뮬레이터 세션의 경우, GitHub Actions 가이드에 문서화된 GitHub Actions 통합 기능을 사용하십시오.
빠른 시작
이름 또는 UDID로 특정 시뮬레이터를 지정하려면, 이를 유일한 인수로 전달하십시오:
simdeck "iPhone 17 Pro Max"
브라우저를 자동으로 열려면 simdeck --open을 사용하고, 기본값이 아닌 포트를 사용하려면 simdeck -p 4311을 사용하며, 로그인 자동 시작을 위해 서비스를 등록하려면 simdeck -a를 사용하십시오.
제공되는 루프백(loopback) 브라우저 UI는 생성된 API 접근 토큰(API access token)을 자동으로 받습니다. LAN 클라이언트는 API 쿠키(API cookie)를 받기 전에 인쇄된 코드로 페어링해야 합니다.
SimDeck iOS 앱과 페어링하는 경우:
이는 LaunchAgent 기반의 SimDeck 서비스를 시작하거나 새로 고치며, 사용 가능한 경우 로컬(local), LAN 및 Tailscale URL을 인쇄하고 simdeck://pair 링크가 포함된 QR 코드를 표시합니다. 이 QR 코드에는 페어링 코드와 감지된 모든 비루프백 주소(non-loopback addresses)가 포함되어 있으므로, 한 번의 페어링으로 동일한 서비스 토큰과 함께 LAN 및 Tailscale 경로를 모두 저장할 수 있습니다.
일반적인 서비스 재시작은 해당 토큰을 유지하므로, 페어링된 클라이언트는 연결 상태를 유지합니다. 서비스 토큰을 순환하고 LaunchAgent를 다시 시작하려는 경우에만 simdeck service reset을 사용하십시오.
서비스는 -p 또는 --port를 전달하거나 ~/.simdeck/config.json에 기본값을 설정하지 않는 한 포트 4310을 사용합니다.
SimDeck 소유의 Android 에뮬레이터 부트는 기본적으로 호스트 GPU 렌더링(host GPU rendering)을 사용합니다. macOS에서는 네이티브 에뮬레이터 창을 표시하지 않으면서 Qt 렌더러가 활성 상태를 유지하도록 -qt-hide-window로 에뮬레이터를 시작합니다. 관리형 부트(Managed boots)는 또한 이벤트 기반 Android 비디오 캡처를 위해 에뮬레이터 gRPC 엔드포인트(gRPC endpoint)를 열고, shared-video 폴링을 대체 수단으로 유지합니다. simdeck service restart --android-gpu auto 또는 --android-gpu swiftshader_indirect는 기기별 대체 수단으로만 사용하십시오.
관리형 Android 부트는 또한 기본적으로 -no-audio를 추가합니다. 에뮬레이터 오디오가 필요한 경우 ~/.simdeck/config.json에서 android.disableAudio를 false로 설정하십시오.
다른 체크아웃에서 시작했거나 설치된 바이너리를 포함하여 모든 SimDeck 서비스 프로세스를 중지하려면 simdeck service kill을 사용하십시오.
CLI 명령어는 자동으로 동일한 워밍업(warm) 서비스를 사용합니다:
simdeck list
simdeck use <udid>
simdeck tap 0.5 0.5 --normalized
...
CLI
simdeck list
simdeck use <udid>
simdeck boot <udid>
...
simdeck list는 에이전트 친화적인 장치 선택을 위해 기본적으로 간결한 JSON 형식을 사용합니다. 경로 및 표시 메타데이터가 포함된 전체 인벤토리는 simdeck list --format json을 사용하십시오.
simdeck use <udid>는 현재 프로젝트 디렉터리에 기본 시뮬레이터를 저장합니다. 대부분의 장치 명령어는 [<udid>]를 허용하며, 이를 생략할 경우 SimDeck은 --device, SIMDECK_DEVICE, SIMDECK_UDID, 저장된 프로젝트 기본값, 또는 유일하게 부팅된 시뮬레이터 순서로 사용합니다.
camera start는 SimDeck 데몬(daemon)에게 카메라 피드를 게시하도록 요청하고, 대상 iOS 시뮬레이터 앱에 SimDeck 카메라 슁(shim)을 주입한 다음 해당 번들(bundle)을 재실행합니다. 소스는 생성된 패턴, 절대 이미지 또는 비디오 경로, http://, https://, 또는 file:// 비디오 URL, 또는 --webcam [id-or-name]으로 선택된 Mac 카메라일 수 있습니다. UI에서 동일한 흐름을 사용하려면 브라우저 메뉴 항목 **Camera Simulation...**을 사용하십시오. 카메라 시뮬레이션은 iOS 시뮬레이터 전용이며 부팅된 시뮬레이터를 필요로 합니다.
JS/TS 테스트
import { connect } from "simdeck/test";
const sim = await connect({ udid: "<udid>" });
...
connect()는 필요할 때 SimDeck 서비스를 시작하고 이미 정상 상태일 때는 이를 재사용합니다. 세션 메서드의 기본값으로 설정하려면 connect()에 udid를 전달하십시오. 각 메서드는 여전히 필요할 때 명시적인 UDID를 첫 번째 인수로 허용합니다. tree(), query(), waitFor(), assert(), 그리고 선택자 tapElement()와 같은 쿼리 도우미(Query helpers)는 빠른 에이전트 제어를 위해 기본적으로 source: "native-ax"를 사용하며, 테스트가 의도적으로 더 풍부한 프레임워크 인스펙터 트리(framework inspector trees)를 먼저 원할 때는 source: "auto"를 전달하십시오.
NativeScript Inspector
⚠️ [IMG:N]
NativeScript 앱은 JavaScript(JS)에서 실행 중인 서버에 직접 연결하여, Swift 인스펙터 프레임워크를 링크할 필요 없이 NativeScript 논리적 계층 구조와 원시 UIKit 백킹 뷰를 노출할 수 있습니다:
import { startSimDeckInspector } from "@nativescript/simdeck-inspector";
if (__DEV__) {
...
런타임은 WebSocket으로 GET /api/inspector/connect에 연결됩니다. Rust 서버는 계층 구조 요청 시 연결된 NativeScript 인스펙터를 선호하며, 일치하는 앱 인스펙터가 없을 경우 Swift TCP 인스펙터 또는 내장 네이티브 접근성 브릿지(native accessibility bridge)로 폴백합니다.
React Native Inspector
React Native 앱은 React Native 인스펙터 패키지를 사용하여 컴포넌트 트리와 Metro 개발 모드 소스 위치를 노출할 수 있습니다:
import "react-native-simdeck/auto";
import "expo-router/entry";
패키지가 React Fiber 커밋을 캡처할 수 있도록 expo-router/entry 또는 AppRegistry.registerComponent(...)보다 먼저 임포트해야 합니다. 자동 진입점(auto entrypoint)은 개발 환경 외부에서는 아무 작업도 수행하지 않으며, 존재하면 EXPO_PUBLIC_SIMDECK_PORT를 읽고 그렇지 않으면 일반적인 SimDeck 서비스 포트를 스캔합니다.
Flutter Inspector
Flutter 앱은 Flutter 인스펙터 패키지를 사용하여 위젯 트리, 렌더 프레임(render frames), 시맨틱 메타데이터(semantics metadata), 그리고 디버그 위젯 생성 위치를 노출할 수 있습니다:
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:simdeck_flutter_inspector/simdeck_flutter_inspector.dart';
...
기여 (Contributing)
기여자들은 로컬 빌드 지침, 개발 워크플로우(dev workflow), 아키텍처 노트는 CONTRIBUTING.md를 읽어보아야 합니다.
저작권 고지 (Copyright notice)
Copyright OpenJS Foundation 및 NativeScript 기여자들의 저작권입니다. 모든 권리가 보호됩니다. OpenJS Foundation은 등록 상표를 보유하고 사용합니다. OpenJS Foundation의 상표 목록은 당사의 상표 정책 및 상표 목록을 참조해 주십시오. OpenJS Foundation 상표 목록에 표시되지 않은 상표와 로고는 해당 소유자의 상표™ 또는 등록® 상표입니다. 이를 사용한다고 해서 그들(소유자)과 제휴 관계이거나 보증한다는 것을 의미하지 않습니다.
OpenJS Foundation | 이용 약관 | 개인정보 처리방침 | OpenJS Foundation 정관 | 상표 정책 | 상표 목록 | 쿠키 정책
<h3 align="center">❤️ 제작</h3>
