> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# C++ 테스트

> 로컬 VillageSQL 서버를 설정하고, MTR로 확장 회귀 테스트를 실행하며, 테스트 실패를 디버깅하세요.

이 가이드는 C++ 확장의 테스트-반복 루프를 다룹니다: 로컬 서버 설정, `.veb` 파일 설치, 회귀 테스트 실행, 실패 디버깅. 초기 빌드를 다루는 [C++로 확장 만들기](/docs/ko/mysql-8.4/0.0.5/create), 그리고 VDF 작성 심층 내용을 다루는 [C++ 개발](/docs/ko/mysql-8.4/0.0.5/development)의 동반 자료입니다.

<Note>
  확장을 빌드하는 것이 아니라 VillageSQL 서버 자체에 기여하는 경우, `mysql-test-run.pl`을 직접 사용하여 테스트를 실행하는 것을 포함한 전체 서버 개발자 워크플로를 다루는 [소스에서 빌드하기](/docs/ko/mysql-8.4/0.0.5/source)를 참조하세요.
</Note>

## 환경 설정

확장을 개발하고 테스트하려면 빌드된 VillageSQL 서버가 필요합니다. [클론 후 소스에서 빌드하기](/docs/ko/mysql-8.4/0.0.5/source) 가이드를 따라 서버 바이너리를 컴파일하세요.

빌드가 완료되면 `villagesql` CLI를 사용하여 로컬 개발 서버 인스턴스를 관리하세요. 모든 명령은 VillageSQL이 설치된 디렉터리에서 실행하세요.

### 로컬 개발 서버 시작하기

서버 인스턴스를 초기화하고 시작합니다:

```bash theme={null}
./villagesql init    # initialize database and seed bundled extensions
./villagesql start   # start the server (default port 3307)
./villagesql status  # check the server is running
./villagesql connect # open a mysql shell
./villagesql stop    # stop the server
```

초기화 시 root 비밀번호를 설정하려면:

```bash theme={null}
./villagesql init --password
./villagesql start
```

테스트 실행을 위해 mysqld 기능을 활성화하거나 비활성화하려면 `--`
구분자 뒤에 플래그를 전달하세요; 그 뒤의 모든 것은 그대로 `mysqld`로 전달됩니다:

```bash theme={null}
./villagesql start -- --skip-name-resolve --general-log
```

`--` 앞에 있는 인식되지 않는 인수는 거부되므로, `mysqld`에 전달하려는 모든
플래그에는 `--`를 사용하세요.

여러 독립 인스턴스를 관리하려면 명령 앞에 `--dir <path>`를 전달하거나, 현재 작업 디렉터리에 서버 디렉터리를 만들려면 `--here`를 사용하세요:

```bash theme={null}
./villagesql --here init
./villagesql --here start
```

### 확장 파일 관리

SQL을 통해 확장을 설치하기 전에, 해당 `.veb` 파일이 서버에 존재해야 합니다. CLI는 서버의 `lib/veb/` 디렉터리를 관리합니다:

```bash theme={null}
./villagesql veb add /path/to/my_extension.veb  # copy a .veb to the server
./villagesql veb ls                              # list available .veb files
./villagesql veb rm my_extension                # remove a .veb file
```

`init` 전에 `lib/veb/`에 배치된 `.veb` 파일은 자동으로 시딩됩니다. 파일을 추가한 후에는 SQL을 통해 확장을 설치하세요:

```sql theme={null}
INSTALL EXTENSION my_extension;
```

## 회귀 테스트 실행

VillageSQL 빌드 디렉터리에서 MySQL Test Runner를 사용하여 확장 회귀 테스트를 실행하세요.

### 전체 스위트 실행

확장의 모든 테스트를 실행하려면:

```bash theme={null}
cd $BUILD_HOME
./mysql-test/mysql-test-run.pl --suite=/path/to/your/extension/mysql-test --parallel=auto
```

### 개별 테스트 실행

단일 테스트 케이스를 실행하려면 스위트 경로와 테스트 이름을 지정하세요:

```bash theme={null}
cd $BUILD_HOME
./mysql-test/mysql-test-run.pl --suite=/path/to/your/extension/mysql-test my_test_name
```

## 새 테스트 만들기

새 기능을 추가하거나 버그를 수정할 때는 그에 상응하는 회귀 테스트를 추가해야 합니다.

### 테스트 위치

확장 테스트는 VillageSQL 서버의 `mysql-test/suite/` 트리가 아니라, 확장 자체 저장소의 `mysql-test/` 디렉터리 아래에 위치합니다.

* 테스트 파일은 `.test`로 끝나며 `mysql-test/t/`에 들어갑니다.
* 예상 결과 파일은 `.result`로 끝나며 `mysql-test/r/`에 들어갑니다.

예를 들어, `my_extension`이라는 확장의 경우:

* `mysql-test/t/my_new_test.test`
* `mysql-test/r/my_new_test.result`

### 테스트 파일 규칙

일반적인 확장 테스트는 확장을 설치하고, SQL을 실행한 다음, 제거합니다:

```sql theme={null}
# Description of the test

INSTALL EXTENSION my_extension;

# ... Your Test Code Here ...
CREATE TABLE t1 (val MYTYPE);
INSERT INTO t1 VALUES ('some_value');
SELECT * FROM t1;
DROP TABLE t1;

UNINSTALL EXTENSION my_extension;
```

테스트 출력에 테스트 러너의 임시 디렉터리 경로가 포함되는 경우, `.test` 파일 안에 다음 지시어를 추가하여 경로를 정규화하세요 — 이것이 없으면 기록된 결과에 절대 경로가 포함되어 다른 머신에서 깨집니다:

```sql theme={null}
--replace_result $MYSQLTEST_VARDIR MYSQLTEST_VARDIR
```

### 테스트 추가 단계

1. 확장의 `mysql-test/t/` 디렉터리에 **`.test` 파일을 만듭니다**.
2. 확장의 `mysql-test/r/` 디렉터리에 **빈 `.result` 파일을 만듭니다**.
3. 예상 출력을 생성하기 위해 **`--record`로 테스트를 실행합니다**:
   ```bash theme={null}
   cd $BUILD_HOME
   ./mysql-test/mysql-test-run.pl --suite=/path/to/your/extension/mysql-test --record my_new_test
   ```
4. 생성된 `.result` 파일이 예상과 일치하는지 **확인합니다**.

## 테스트 디버깅

테스트가 실패하면 테스트 프레임워크가 상세한 로그를 제공합니다.

* **테스트 출력:** `mysql-test/var/log/mysqltest.log`(통합 로그) 또는 `mysql-test/var/log/<test_name>/`(테스트별 디렉터리)를 확인하세요.
* **서버 오류 로그:** `mysql-test/var/log/mysqld.1.err`를 확인하세요. VillageSQL 전용 로그 메시지(`LogVSQL()`을 통해 출력됨)는 서버가 `--log-error-verbosity=3`으로 실행될 때만 나타납니다.
* **Diff:** 프레임워크는 실제 출력과 예상 `.result` 파일 사이의 diff를 출력합니다.

추가 디버그 정보와 함께 테스트를 실행하려면:

```bash theme={null}
cd $BUILD_HOME
./mysql-test/mysql-test-run.pl --verbose --suite=/path/to/your/extension/mysql-test my_new_test

# To surface LogVSQL() messages in the error log:
./mysql-test/mysql-test-run.pl --mysqld=--log-error-verbosity=3 \
    --suite=/path/to/your/extension/mysql-test my_new_test
```

## 참고

* [네트워크 의존 확장 테스트](/docs/ko/mysql-8.4/0.0.5/testing-network) — HTTP 서버나 외부 리스너를 생성하는 확장을 위한 안정적인 MTR 패턴
* [C++로 확장 만들기](/docs/ko/mysql-8.4/0.0.5/create) — 종단간 빌드 단계, CMake 설정, 설치
* [C++ 개발](/docs/ko/mysql-8.4/0.0.5/development) — VDF 작성 심층 내용, 인자 및 결과 타입, 집계, 가변 인자
* [C++ API 참조](/docs/ko/mysql-8.4/0.0.5/extension-api-reference) — VDF 계약, null 처리, 버퍼 크기 조정