App 테스트하기
App 소스·계약 테스트를 실행하고 실제 샌드박스 동작을 확인합니다.
App 테스트하기
Resource 만들기 이후 App 저장소에서 검사합니다. Core 소스·Core 테스트 클래스·운영자 DB 계정은 필요하지 않습니다.
nexia check
composer install --no-scripts
nexia testnexia check는 App 코드를 실행하지 않고 metadata와 PHP 문법을 확인합니다.
nexia test는 App 테스트 코드를 실행합니다. 생성된 Resource 테스트는
소유권·권한 선언을 검사하며 HTTP 인가나 데이터 저장까지 증명하지 않습니다.
tests/Pest.php와 phpunit.xml은 App 소유이며 Core의 Tests\TestCase를 상속하지 않습니다.
게시용 아티팩트 검사도 앱의 phpunit.xml 테스트 구성을 사용합니다. 앱과 공개 SDK만으로 실행할 수 있는 테스트를 지정하고, Core 통합 테스트는 호스트 테스트에서 계속 실행하세요. 빈 테스트 모음은 실패합니다. 실행기는 별도로 서명된 요청의 인증, 마이그레이션, 리소스 계약을 검사합니다. 임시 검사 DB에는 문서에 공개된 Core 외래 키 대상 ID 구조만 준비하며, 마이그레이션 계정에 REFERENCES 권한만 부여합니다. Core 데이터나 조회 권한은 제공하지 않습니다.
DB 저장을 검사하려면 nexia test --database를 실행합니다. Docker가 로컬 루프백 포트에 임시 PostgreSQL을 만들고 실행 후 제거합니다. App 테스트 환경은 NEXIA_TEST_DB_HOST와 NEXIA_TEST_DB_PORT를 읽고 자체 migration과 SDK 계약 대역을 준비합니다. --filter 또는 --testsuite로 범위를 좁힐 수 있습니다. 로컬 PHP와 App 개발 의존성이 필요하며 로그인이나 Core 소스는 필요하지 않습니다. App의 PHPUnit 설정이 선택한 테스트만 실행됩니다.
산출물 PHP 테스트에도 컨테이너 네트워크를 차단한 임시 PostgreSQL이 Unix 소켓으로 제공됩니다. TCP를 가정하지 말고 NEXIA_TEST_DB_HOST를 사용하세요. 이 DB는 migration 승인 검사와 보관 중인 샌드박스 데이터에서 분리됩니다. 업무 기본값과 상태 검사가 실행되도록 Eloquent 모델 이벤트를 켜 두세요.
개발 샌드박스 권한
개발 앱 준비가 정상 완료되면 샌드박스의 계정 소유자 역할에 현재 실행 가능한 앱 권한이 자동 반영됩니다. 다른 사용자·일반 역할에는 자동 부여하지 않습니다. 권한 거부를 시험하려면 별도 사용자에게 필요한 역할과 법인·운영 조직 범위를 명시적으로 부여하세요. 게시 앱 설치와 운영 환경의 권한 정책은 바뀌지 않습니다.
개인 개발 샌드박스에서 초대 사용자가 시크릿 창 등에서 일반 로그인하면, 로그인 직후 샌드박스 접근 검사에서 로그아웃되고 /home이 403을 반환할 수 있습니다. 법인 참여나 역할 부여만으로 개인 샌드박스에 직접 로그인할 수 있는 것은 아닙니다. 다른 사용자 권한은 소유자가 시작하는 이 사용자로 테스트로 확인하세요.
- 샌드박스 소유자로 접속하고 디렉터리 → 사용자에서 이메일 인증을 완료한 활성 테스트 사용자를 선택합니다.
- 필요한 역할과 법인·운영 조직 범위를 부여합니다. 권한 거부를 확인하려면 해당 권한을 부여하지 않습니다.
- 사용자 상세에서 이 사용자로 테스트를 선택하고, 대상 사용자의 실제 권한으로 조회·저장·승인 동작을 확인합니다. 기존 개발 앱 연결은 유지됩니다.
- 테스트를 마치면 상단의 개발자로 복귀를 선택합니다.
전환은 같은 브라우저 세션의 다른 샌드박스 탭에도 영향을 주므로 작성 중인 내용을 먼저 저장하세요. 테스트 중 저장·승인·삭제는 샌드박스 데이터에 실제 반영됩니다. 자세한 절차는 빠른 시작의 ‘다른 사용자 권한으로 테스트’를 참고하세요.
개발 샌드박스는 선택한 개발 앱을 실행합니다. 게시 앱 설치는 일반 테넌트에서 진행합니다.
프로젝트 소유자는 설정에서 이름을 확인한 뒤 빈 프로젝트를 삭제할 수 있습니다. 앱, 샌드박스, 구성원, 초대, 연결이나 개발·사용 이력이 있는 프로젝트는 삭제할 수 없습니다. 기존 기록과 게시된 앱은 유지됩니다. Core 변경
테스트 메일 확인
샌드박스에서 Core가 보내는 알림과 업무 메일은 실제 수신자에게 전달하지 않고 테스트 메일함에 저장합니다. 샌드박스에서 설정 → 메일 발송 이력 → 테스트 메일함을 열어 수신자, 내용과 첨부파일을 확인하세요. 이 화면에는 테넌트 전체 알림 발송 이력 조회 권한이 필요합니다. 최근 50건을 표시하며 보관은 최대 7일이고, 공용 저장 한도에 도달하면 더 일찍 삭제될 수 있습니다. 실제 메일 서버의 수신이나 스팸 판정은 검증하지 않습니다. App이 Core를 거치지 않고 직접 SMTP를 사용하는 경우는 이 기능에 포함되지 않습니다.
로컬 개발 조회와 종료
프로젝트 또는 앱 폴더에서 nexia ps를 실행하면 기록된 로컬 세션의 포트, PID, 선택한 앱과 워크스페이스 링크를 확인할 수 있습니다. nexia stop --port 4310으로 한 세션을, nexia stop으로 현재 프로젝트의 로컬 개발을 종료합니다. GPT가 실행했어도 다른 터미널에서 사용할 수 있으며 샌드박스 데이터는 보존합니다. 이전 CLI로 시작한 세션은 기록되지 않아 Ctrl+C 또는 수동 포트 확인이 필요합니다. Docker 안에서 시작했다면 같은 컨테이너 안에서 조회·종료하세요.
nexia status와 콘솔 앱 목록에는 Git 연결, 마지막으로 확인한 Git 태그, 최근 제출 태그, 게시 버전과 현재 플랫폼 환경의 배포 버전이 구분되어 표시됩니다. Git 태그를 갱신하려면 저장소 링크를 여세요. 배포 버전은 개별 테넌트의 설치 버전이나 로컬 실행 상태와 다릅니다.
개발 앱이 변경되면 새 런타임으로 전환할 수 있을 때 해당 앱의 번역도 갱신됩니다. 저장하지 않은 작업이나 이전 프런트엔드 계약 때문에 전환이 대기하면 작업을 저장한 뒤 화면의 새로고침을 사용하세요. 다른 앱과 Core의 번역은 유지됩니다. Core 런타임
Docker
생성된 개발 이미지에는 PHP와 Composer가 포함됩니다.
docker compose build
docker compose run --rm dev check
docker compose run --rm --entrypoint composer dev install --no-scripts
docker compose run --rm --entrypoint composer dev testApp 생성 때와 같은 UID/GID 설정을 사용합니다. 테스트 DB는 샌드박스의 유지되는 데이터와 분리합니다. 연결을 통과시키려고 운영자 DB 인증정보를 복사하거나 다른 DB 호스트로 임의 변경하지 않습니다.
변경 동작 확인
| 변경 | 필요한 근거 |
|---|---|
| Resource 필드 | 인가된 생성·수정·조회, nullable 값 비우기, 잘못된 입력 거부 |
| 권한·소유권 | 허용·거부 사용자, 다른 조직·테넌트, 목록과 단건 접근의 일치 |
| migration | 기존 행 보존과 DB 제약의 잘못된 쓰기 거부 |
| 이벤트 처리 | 중복 전달의 효과 1회, 문맥 누락·권한 회수 시 거부 |
| 필수 초기화 | 재시도 시 기본값·운영자 수정 보존과 중복 방지 |
테스트는 App의 tests/에 둡니다. 공개 SDK 계약과 App 소유 fixture를 사용하며
Core Eloquent 모델을 import하지 않습니다. mock 테스트는 그 mock 조건의 로컬
동작을 검증합니다. 실제 호스트 경계는 샌드박스에 App을 설치하고 의도한 사용자
권한으로 별도 확인합니다. 설치만으로 사용자에게 권한이 생기지는 않습니다.
PHP SDK 0.10으로 올릴 때는 제거된 테스트 계약 Nexia\Laravel\Testing\Contracts\HostTestModelStore, Nexia\Laravel\Testing\HostTestStore, Nexia\Testing\Contracts\HostTestStore를 앱 소유 Pest fixture와 공개 호스트 계약으로 바꾸세요. nexia test 또는 nexia test --database를 실행한 뒤 실제 런타임 경계를 별도로 확인합니다. 기존 앱은 승인된 PHP SDK 0.9 아티팩트와 호환 런타임을 유지할 수 있으며, 모든 앱을 업그레이드해야 하는 것은 아닙니다.
앱의 Vitest 의존성을 설치한 뒤 nexia test --frontend를 실행합니다. --filter로 테스트 이름을 선택할 수 있으며, --frontend와 --database·--testsuite는 함께 사용할 수 없습니다. 선택된 테스트가 없으면 통과 근거가 아닙니다.
권한을 유지하면서 목록 성능 확인
분리된 앱 테스트 DB에 서로 다른 레코드 여러 개와 의존 데이터를 준비합니다. 한 행을 반복한 데이터로 대신하지 마세요. 실제 행이 채워진 작은 페이지와 큰 페이지에서 변경한 부가 조회의 SQL·호스트 호출 횟수를 비교하고, 장비마다 달라지는 밀리초 제한보다 조회 횟수가 행마다 증가하지 않는지 검증합니다. 빈 페이지, 목록 조회 후 의존 데이터 추가·삭제, 해당 업무의 논리 삭제, 권한 밖의 레코드도 포함합니다. 호출 횟수뿐 아니라 응답 값도 확인하세요. 필수 검사나 데이터를 빠뜨려서 빨라진 결과는 실패입니다.
시간을 잴 때는 소스 버전, 실행 방식, 반환 행 수, 페이지 크기, 사용자·조직 권한과 측정 시작·끝을 기록합니다. 데이터와 환경 조건을 맞추고 첫 요청과 캐시가 준비된 반복 요청을 나눠 표본 수·중앙값을 보고하세요. 앱 SQL, 플랫폼 콜백, 전체 HTTP, 브라우저 표시 시간은 서로 다른 수치입니다. 부팅 뒤에 시작한 타이머로 전체 요청 시간을 주장하거나, 한 행으로 큰 목록·동시 처리 성능을 판단하지 않습니다. 측정 기록에는 토큰이나 업무 응답 본문을 남기지 마세요.
게시 앱 버전 간 성능은 같은 계약·데이터로 비교합니다. 앱 개발자가 이를 위해 Core를 배포하거나 운영 DB에 접근할 필요는 없습니다. DB 크기·권한이 다르거나 한쪽 결과만 비어 있다면 시간 차이를 컨테이너 비용으로 단정할 수 없습니다. Core와 앱을 따로 측정한 개선 시간을 더하지 말고, 두 변경이 함께 게시된 실행에서 최종 결과를 확인하세요. 구현 기준은 보호된 API 추가하기의 페이지 단위 조회를 참고합니다.
검증 기록
App 소스 revision, 실행한 검사, 관찰한 샌드박스 동작을 기록합니다. Nexia 워크스페이스에서 탭 전환·Inspector·상세·편집과 저장 후 새로고침을 확인합니다. 같은 소스 상태의 성공 근거는 재사용합니다. 로컬 문법·계약 검사, 원격 실행 검사, 심사 승인, 테넌트 설치는 각각 별도 결과입니다.
후보가 준비되면 App 릴리스하기로 이어갑니다.
앱 단독 거절 테스트 추가
업무 프로세스로 노트 작업 실행하기의 handler를 구현한 뒤 tests/ProcessWorkActionTest.php에 넣습니다. 생성된 Pest 설정·SDK 인터페이스만 사용하며 Core 부팅이나 DB 연결이 필요하지 않습니다.
<?php
declare(strict_types=1);
use Nexia\Apps\Acme\Workshop\Process\ArchiveNoteProcessWorkActionHandler;
use Nexia\Identity\Contracts\Actor;
use Nexia\Organization\Contracts\LegalEntity;
use Nexia\Process\Domain\ProcessWorkActionException;
use Nexia\Process\ProcessWorkActionInvocation;
use Nexia\ResourceReference\ResourceRef;
test('archive rejects a different resource before accessing the database', function (): void {
$invocation = new ProcessWorkActionInvocation(
appKey: 'workshop',
actionKey: 'note.archive',
descriptorVersion: '1.0',
processInstancePublicId: 'ac0588d8-8d86-4f4e-9ddf-202a9dafcb06',
externalTaskKey: 'task-1',
idempotencyKey: 'archive-task-1',
legalEntity: $this->createMock(LegalEntity::class),
actor: $this->createMock(Actor::class),
resourceRef: new ResourceRef(
'workshop', 'workshop.example',
'd7c1c7c4-f1a5-4886-afaa-e3eaa687e91d', 'Different record',
),
input: [],
);
try {
(new ArchiveNoteProcessWorkActionHandler)->handle($invocation);
$this->fail('Expected a resource mismatch.');
} catch (ProcessWorkActionException $exception) {
expect($exception->errorCode)->toBe('workshop_note_resource_mismatch');
}
});nexia test --filter='archive rejects'로 실행합니다. 이 검사는 다른 Resource가 DB 접근 전에 거절되는지 확인합니다. 허용된 쓰기·Policy 복원·worker 등록을 검증한 것은 아닙니다. 해당 검사는 앱 소유 binding과 격리된 테스트 DB를 준비하고 실제 샌드박스 확인을 병행하세요. 생성기가 Core HTTP 단독 harness를 제공하지는 않습니다. Core의 Tests\TestCase를 상속하거나 로컬 테스트를 보관 중인 샌드박스 DB에 연결하지 않습니다.
브라우저 통합 확인은 서로 다른 권한을 명시적으로 부여한 테스트 사용자 두 명으로 진행합니다. 생성 → 목록 → 상세 → 수정 → 저장 → 재조회, 거절된 쓰기·다른 조직을 확인하세요. cookie·bearer token 없이 상태와 작업 ID만 기록합니다. 비동기 작업은 접수와 완료 결과를 분리해서 기록합니다.
호스트 신원 조회 결과는 Core 모델이 아니라 SDK 인터페이스입니다. Party는
publicId()·displayLabel()을 제공하며 public_id·display_name·legal_name
속성을 보장하지 않습니다. 개인 프로필 값은 PersonProfileDirectory 또는
BatchPersonProfileDirectory가 반환하는 PersonProfileView로 읽습니다. 권한을
확인한 페이지의 키만 일괄 조회하고, 법적 이름이 없다고 표시 이름으로 대체하지
않습니다. 인터페이스만 구현한 대역과 서로 다른 프로필 DTO 여러 개, 빈 페이지로
검증하세요. 단건 디렉터리에 예상하지 않은 호출이 오면 테스트를 실패시켜 행별
조회가 게시 전에 발견되도록 하고, 호출 횟수와 응답 값 모두 확인합니다.
목록의 상태·건수 표시에는 하위 레코드 전체를 객체로 읽는 대신 집계나 EXISTS를 사용합니다. 작은 페이지에도 수천 개의 하위 레코드가 연결될 수 있습니다. 상태 우선순위·유효일 경계·삭제 처리 결과가 상세 계산과 같은지 확인합니다. 하위 데이터가 일부 행에 몰린 전체 페이지도 측정합니다. 여러 상관 EXISTS가 같은 테이블을 반복 스캔하면, 권한 확인을 마친 현재 페이지 ID만 대상으로 필요한 상태를 한 번에 그룹 집계합니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.
반복 호출과 화면 대기를 회귀 테스트로 막기
성능 관련 변경에는 시간만 비교하지 말고 호출 횟수와 의존 순서를 검증하세요. 시간 기준은 환경마다 달라지므로 임의의 공통 밀리초 합격선을 만들지 않습니다.
| 변경 경로 | 테스트에서 확인할 것 |
|---|---|
| 목록 부가 정보 | 1행·25행·빈 페이지를 비교해 호스트 호출이 행마다 늘지 않음. 공개 배치 크기를 넘으면 필요한 청크 수만 증가 |
| 조직 권한 | 선택한 법인의 정확한 허용 대상을 한 번 조회. 대상 없음·거부는 동작을 노출하지 않고 다른 법인 권한을 재사용하지 않음 |
| 상세/목록 전환 | 숨겨진 목록의 필터가 남아 있어도 상세 진입 시 그 목록을 새로 요청하지 않음. 표시 중인 검색은 계속 작동 |
| 독립 조회 | 한 응답을 미완료 상태로 둬도 의존하지 않는 조회가 시작됨. 권한·선택 대상이 필요한 조회는 그 결과를 기다림 |
| 재사용과 갱신 | 사용자·조직 변경, 권한 회수, 저장 후 재조회에서 이전 결과가 잘못 재사용되지 않음 |
| 누락된 참조 | 배치에서 빠진 ID를 단건으로 반복 재시도하지 않으며, 존재 여부를 노출하지 않음 |
SDK 대역의 호출 수 테스트는 요청 구조를 확인합니다. 실제 호스트의 DB 비용이나
브라우저 체감 시간을 증명하지 않으므로, 같은 사용자·데이터·페이지 크기의
샌드박스 관측을 별도로 기록하세요. nexia check와 제출 심사를 통과했다고 이 표의
조건을 자동으로 검사했다고 보고하지 않습니다. 현재 정적 검사는 임의의 앱에서
N+1이나 숨겨진 React 조회를 완전히 탐지하지 못합니다.
외부 앱의 샌드박스 로그인 시험
외부 앱은 샌드박스의 Authorization Code + PKCE S256 경로를 사용합니다. 개발자 콘솔 계정과 샌드박스 사용자는 별개입니다. 같은 이메일이어도 콘솔 비밀번호나 Google 연결이 샌드박스에 복사되지 않습니다.
샌드박스에 로그인하지 않은 브라우저에서 외부 앱의 로그인을 시작하면 개발자 콘솔 인증을 거쳐 본인 샌드박스로 돌아온 뒤 API 접근 동의를 받습니다. 콘솔에서 지원하는 Google·GitHub 또는 계정 비밀번호로 인증하세요. 샌드박스의 임의 생성된 초기 비밀번호를 입력하거나 별도 Google 공급자를 등록할 필요가 없습니다. 이미 샌드박스에 로그인했거나 이 사용자로 테스트 중이면 해당 사용자로 동의를 진행합니다.
- 소유자로 샌드박스 워크스페이스를 열고 설정 → Developer API에서 사용자 로그인 연결을 등록합니다. 샌드박스의 실제 origin과 Client ID를 사용하세요. demo·운영·다른 샌드박스의 연결은 사용할 수 없습니다.
- 앱 복귀 주소를 정확히 등록합니다. Flutter·.NET 모바일은 OS에 등록한 HTTPS 또는
com.example.client:/oauth/callback같은 앱 스킴을, 데스크톱은 앱 스킴 또는http://127.0.0.1:43120/callback같은 loopback 수신 주소를 사용합니다. HTTP loopback IP 주소(127.0.0.1또는[::1])는 실행 시 포트가 달라도 되며 나머지 주소 구성은 일치해야 합니다. 다른 복귀 주소는 정확히 일치해야 합니다. - 앱에서 새
state와 PKCE verifier·S256 challenge를 생성하고 시스템 브라우저로https://<sandbox>/oauth/developer-api/authorize를 엽니다.response_type=code,client_id,redirect_uri,state,code_challenge_method=S256,code_challenge를 전달합니다. 선택적으로 등록된 operation ID를 공백으로 연결한scope를 전달합니다. - 새 브라우저라면 그 샌드박스를 소유한 개발자 계정으로 콘솔에 로그인합니다. 다른 개발자나 프로젝트 열람 권한만 있는 계정으로 대신 접속할 수 없습니다. 모바일 인증 브라우저는 PC의 로그인 세션을 공유하지 않을 수 있습니다. 앱으로 복귀할 때까지 동일한 인증 브라우저 세션을 유지하세요.
- 동의 화면의 계정과 대상 샌드박스를 확인하고 허용합니다. 앱 콜백에서 원래
state와iss=https://<sandbox>/oauth/developer-api를 확인합니다. 거절된 요청은error=access_denied로 처리하며 토큰 교환을 시도하지 않습니다. POST https://<sandbox>/oauth/developer-api/token에 form 본문으로grant_type=authorization_code,client_id,code, 인가 요청에 사용한redirect_uri, 원래code_verifier를 보냅니다. public 앱에는 Client Secret을 넣지 않습니다. 반환된 bearer는 OS 보안 저장소에 보관하고 URL·로그에 출력하지 마세요.- 같은 bearer로
GET https://<sandbox>/api/v1/openapi.json을 호출하고, 문서에 있는 권한 있는 조회 operation을 선택해 호출합니다. 원래/api/...경로는/api/v1/...로 호출합니다. 해당 사용자의 현재 역할과 조직 범위가 적용되므로 토큰 발급만으로 모든 API가 허용되지는 않습니다. 변경 API 대신 조회부터 검증하세요. - 다른 권한을 확인하려면 외부 앱의 인증 브라우저에서 콘솔을 통해 샌드박스를 열고 위의 다른 사용자 권한으로 테스트 절차로 전환한 뒤 로그인을 다시 시작합니다. 개발자로 복귀하거나 로그아웃하면 해당 테스트 세션으로 발급한 토큰도 사용할 수 없어야 합니다.
인증 시작은 10분 안에 완료해야 합니다. 새 로그인 시도는 이전 진행 중인 샌드박스 로그인 시도를 대체합니다. 콘솔 인증 후 샌드박스 복귀는 1분 안에 같은 브라우저에서 한 번만 처리됩니다. 만료·취소·세션 변경 시 외부 앱에서 로그인을 새로 시작하세요. 이 경로는 계정을 합치거나 일반 사용자에게 개인 샌드박스 직접 접속을 허용하지 않습니다.
Google·기업 SSO 자체를 시험할 때
콘솔 로그인과 별도로 샌드박스 테넌트의 SSO를 시험하려는 경우에만 테넌트의 SSO 공급자를 설정합니다. Google Client ID·Secret, 공급자 활성화, IdP 허용 정책과 이메일 도메인 제한을 확인하세요. 기업 OIDC·Entra는 해당 조직의 issuer도 필요합니다. Google·IdP에는 https://<sandbox>/auth/sso/<provider-slug>/callback을 등록합니다. 이는 앞서 Nexia에 등록한 외부 앱 복귀 주소와 다릅니다. 샌드박스를 재생성해 origin이 바뀌면 등록도 확인해야 합니다.
기존 샌드박스 사용자와 동일 이메일로 SSO를 처음 연결하면 그 사용자의 기존 비밀번호 확인이 필요할 수 있습니다. 콘솔 비밀번호를 대신 입력하지 마세요. 개인 샌드박스의 일반 사용자는 SSO 인증에 성공해도 소유자 접근 검사에서 거부될 수 있으므로, API 권한 시험에는 소유자가 시작하는 이 사용자로 테스트를 사용하세요. 테넌트에서 외부 사용자로 분류된 계정은 현재 SSO 대상이 아닙니다. 외부 앱 사용 여부와는 별개입니다.
| 증상 | 확인 항목 |
|---|---|
| Google 버튼이 없음 | 콘솔 화면인지 샌드박스 테넌트 화면인지, 해당 공급자의 설정·활성화 |
| IdP의 callback 오류 | IdP에 등록한 Nexia SSO 콜백의 origin·slug |
| 인증 후 403 | 샌드박스 소유 계정·프로젝트 개발 권한·원래 브라우저 세션 |
| 샌드박스 이용 불가 | 활성 상태와 만료 시각 |
| 코드·토큰 교환 실패 | Client ID·origin·앱 콜백·PKCE verifier·코드 만료·중복 교환 |
| 토큰 발급 후 API 거부 | 사용자 실제 권한·조직 범위·연결의 operation·테스트 세션 종료 여부 |
기존 웹 로그인 예제는 로그인과 토큰 발급까지만 구현하며 업무 API 호출·갱신은 포함하지 않습니다. 위 절차는 공통 HTTP 계약의 시험 방법이며 Flutter·.NET 실행 프로젝트나 실제 기기·Google 로그인의 검증 완료를 뜻하지 않습니다.