> ## 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.

# Development

> Setting up a local development environment and running tests for VillageSQL.

This guide covers the essentials of developing for VillageSQL, with a focus on running the comprehensive test suite to ensure code quality and feature correctness.

## Setting Up Your Environment

To develop VillageSQL, you first need to build the server from source. Follow the [Clone and Build from Source](/docs/mysql-8.4/0.0.2/source) guide to clone the repository and compile the binaries.

Once you have a build directory (e.g., `build/`), you are ready to run the regression tests.

## Running Regression Tests

VillageSQL uses the MySQL Test Framework (`mysql-test-run.pl` or `mtr`) for regression testing. The test suite is located in the `mysql-test` directory.

### Running the Full Suite

To run the complete set of VillageSQL-specific tests, including all sub-suites (Insert, Select, Stored Procedures, etc.), use the `--do-suite` option:

```bash theme={null}
cd build
./mysql-test/mysql-test-run.pl --do-suite=villagesql --parallel=auto
```

<Note>
  Using `--suite=villagesql` (without `do-`) typically only runs the top-level tests in the `villagesql` directory and skips the sub-directories. Always use `--do-suite=villagesql` for full coverage.
</Note>

### Running Specific Sub-Suites

VillageSQL tests are organized into sub-suites based on functionality (e.g., `insert`, `select`, `update`). You can run a specific sub-suite to focus on a particular area:

```bash theme={null}
# Run only INSERT tests
./mysql-test/mysql-test-run.pl --suite=villagesql/insert

# Run only SELECT tests
./mysql-test/mysql-test-run.pl --suite=villagesql/select

# Run only Stored Procedure tests
./mysql-test/mysql-test-run.pl --suite=villagesql/stored_procedure
```

Available sub-suites include:

* `villagesql/insert`
* `villagesql/select`
* `villagesql/update`
* `villagesql/delete`
* `villagesql/replace`
* `villagesql/table_dml`
* `villagesql/values`
* `villagesql/handler`
* `villagesql/load_data`
* `villagesql/load_xml`
* `villagesql/stored_procedure`
* `villagesql/prepared_statement`
* `villagesql/trigger`
* `villagesql/view`
* `villagesql/expression`

### Running Individual Tests

To run a single test case, specify the suite path and test name:

```bash theme={null}
# Run a specific insert test
./mysql-test/mysql-test-run.pl villagesql/insert.insert_values_complex
```

## Creating New Tests

When adding new features or fixing bugs, you should add corresponding regression tests.

### Test Location

Tests are located in `mysql-test/suite/villagesql/`. Choose the appropriate sub-directory based on the SQL statement or feature being tested.

* Test files end with `.test` and go in the `t/` directory.
* Expected result files end with `.result` and go in the `r/` directory.

### Test File Conventions

VillageSQL tests often involve the custom `COMPLEX` type. We follow a specific pattern to ensure tests are skipped gracefully if the feature is not yet fully implemented:

```sql theme={null}
# Description of the test
# Grammar: (Optional) SQL syntax reference

--source include/villagesql/not_implemented_complex_type.inc

--source include/villagesql/install_complex_extension.inc

# ... Your Test Code Here ...
CREATE TABLE t1 (val COMPLEX);
INSERT INTO t1 VALUES ('(1.0,2.0)');
SELECT * FROM t1;
DROP TABLE t1;

--source include/villagesql/uninstall_complex_extension.inc
```

### Steps to Add a Test

1. **Create the `.test` file** in the appropriate `t/` directory (e.g., `mysql-test/suite/villagesql/select/t/my_new_test.test`).
2. **Create an empty `.result` file** in the corresponding `r/` directory (e.g., `mysql-test/suite/villagesql/select/r/my_new_test.result`).
3. **Run the test with `--record`** to generate the expected output:
   ```bash theme={null}
   ./mysql-test/mysql-test-run.pl --suite=villagesql/select --record my_new_test
   ```
4. **Verify the output** in the generated `.result` file to ensure it matches your expectations.

## Debugging Tests

If a test fails, `mtr` provides detailed logs.

* **Test output:** Check `build/mysql-test/var/log/my_new_test.log`.
* **Server error log:** Check `build/mysql-test/var/log/mysqld.1.err`.
* **Diff:** `mtr` usually outputs a diff between the actual output and the expected `.result` file.

To run a test with extra debug information:

```bash theme={null}
./mysql-test/mysql-test-run.pl --verbose villagesql/select.my_new_test
```