test: move the suites under integration-tests/ and factor out the shared script paths

`test/` and `windows/` were two top-level directories for one concern, and
`test/` mixed four different things: the shell entry points, the SQL fixture,
the pyodbc suite, and three generated files sitting in the same directory as
the sources. The layout now matches stackable-odbc-trino's, minus everything
that only exists because Trino needs a server:

    integration-tests/
      setup.sh, run-tests.sh    wrappers
      scripts/                  lib.sh + the logic
      suites/                   create_test_db.sql, test_integration.py
      generated/                gitignored wholesale
      windows/                  WINDOWS.md, windows_test.py, vm/

There is no stack/, no compose file and no scripts/teardown.sh: SQLite is a
file and rusqlite links its own copy, so there is nothing to stand up or tear
down. That is also why this suite gates every pull request while Trino's
cannot.

The script cleanup:

- Both scripts derived PROJECT_DIR, DRIVER_PATH and DB_PATH separately, and
  disagreed about which directory DB_PATH lived in relative to the script. They
  now source scripts/lib.sh, which owns those and the ODBCSYSINI/ODBCINI
  export, the driver build, and a setup precondition check.
- Generated output moves out of the source directory into generated/, ignored
  by a `*` .gitignore rather than by naming each file. All of it embeds
  absolute paths, so a committed copy is wrong for everyone but its author.
- run-tests.sh forwarded any unrecognised argument to windows_test.py even
  without --windows, so a typo'd flag produced a full green run that had
  ignored it. Unknown arguments are now rejected unless --windows is given.
- run-tests.sh required setup.sh to have been run and said so nowhere; it now
  checks and points at setup.sh instead of failing inside pyodbc.
- Both take --help, printed from the header comment block by lib.sh's usage()
  rather than a hardcoded line range that truncates as soon as a line is added.
- setup.sh gained --skip-build, and rejects unknown arguments.

shellcheck now runs with -x so it follows lib.sh, the same reason the Trino
repository passes it; without it every sourcing script reports SC1091 for a
file that is right there.

Also fixes two path references that were already stale before the move:
windows/vm/start.yaml pointed at `test/sqlite/windows_test.py`, a path this
repository has never had, and test_integration.py's usage line named itself
under test/.

Verified by running setup.sh and run-tests.sh: 23 pyodbc tests pass DSN-less
and again through the DSN, the require_setup guard fires with the database
removed, and unknown arguments exit 2.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: maltesander

.github/workflows/build.yaml

@@ -101,9 +101,9 @@ jobs:
 
       - name: Run SQLite integration tests
         run: |
-          ./test/setup.sh
+          ./integration-tests/setup.sh
           # --skip-cargo-test: the pre-commit job above already ran it.
-          ./test/run-tests.sh --skip-cargo-test
+          ./integration-tests/run-tests.sh --skip-cargo-test
 
   windows-cross-compile:
     name: Cross-compile Windows DLL

.github/workflows/release.yaml

@@ -68,8 +68,8 @@ jobs:
 
       - name: Run SQLite integration tests
         run: |
-          ./test/setup.sh
-          ./test/run-tests.sh
+          ./integration-tests/setup.sh
+          ./integration-tests/run-tests.sh
 
   build-and-package:
     name: Build and package SQLite release archives

.gitignore

@@ -17,8 +17,8 @@ tags
 # Release packaging output
 packaging/dist/
 
-# Generated by test/setup.sh
-test/test.db
+# integration-tests/generated/ has its own .gitignore; everything setup.sh
+# writes there embeds absolute paths.
 
 # Python bytecode from the test scripts
 __pycache__/

.pre-commit-config.yaml

@@ -25,7 +25,10 @@ repos:
     rev: 2491238703a5d3415bb2b7ff11388bf775372f29 # 0.10.0
     hooks:
       - id: shellcheck
-        args: ["--severity=info"]
+        # -x follows `source`d files. The integration-test scripts share
+        # lib.sh, and without it every one of them reports SC1091 for a file
+        # that is right there and checkable.
+        args: ["--severity=info", "-x"]
 
   - repo: local
     hooks:

AGENTS.md

@@ -33,8 +33,8 @@ cargo test                                   # unit + FFI tests; needs no server
 cargo clippy --all-targets -- -D warnings
 pre-commit run --all-files                   # the gate; run before every commit
 
-./test/setup.sh                              # build driver, create test.db, write ODBC config
-./test/run-tests.sh                          # run the integration suite
+./integration-tests/setup.sh                 # build driver, create the DB, write ODBC config
+./integration-tests/run-tests.sh             # run the integration suite
 ```
 
 ## Relationship to stackable-odbc-core
@@ -534,21 +534,24 @@ with no data source open.
 ### Integration tests
 
 ```bash
-./test/setup.sh          # build, create test/test.db, write odbc.ini/odbcinst.ini
-./test/run-tests.sh      # pyodbc suite through real unixODBC, then cargo test
-./test/run-tests.sh --windows          # also run the Windows VM suite
-./test/run-tests.sh --skip-cargo-test  # pyodbc only; what CI passes
+./integration-tests/setup.sh          # build, create the database, write the ODBC config
+./integration-tests/run-tests.sh      # pyodbc suite through real unixODBC, then cargo test
+./integration-tests/run-tests.sh --windows          # also run the Windows VM suite
+./integration-tests/run-tests.sh --skip-cargo-test  # pyodbc only; what CI passes
 ```
 
-`test/setup.sh` and `test/run-tests.sh` regenerate `test/odbc.ini`,
-`test/odbcinst.ini` and `test/test.db`; all three are gitignored because they
-hold absolute paths.
+Both are wrappers; the logic is in `integration-tests/scripts/`, with the paths
+and helpers they share in `scripts/lib.sh`. Everything `setup.sh` writes lands
+in `integration-tests/generated/`, which is gitignored wholesale because all of
+it embeds absolute paths. See
+[integration-tests/README.md](integration-tests/README.md) for the layout and
+why the pyodbc suite is run twice.
 
 ### Windows VM tests
 
-See [windows/WINDOWS.md](windows/WINDOWS.md). Requires a provisioned libvirt VM;
-`test/windows_test.py` runs the same pyodbc suite over WinRM, DSN-less and then
-via DSN.
+See [integration-tests/windows/WINDOWS.md](integration-tests/windows/WINDOWS.md).
+Requires a provisioned libvirt VM; `integration-tests/windows/windows_test.py`
+runs the same pyodbc suite over WinRM, DSN-less and then via DSN.
 
 ### Benchmarks
 

README.md

@@ -226,13 +226,15 @@ The integration suite goes one layer further out and runs through real
 unixODBC, using Python's `pyodbc` exactly like a normal application would:
 
 ```bash
-./test/setup.sh          # build the driver, create test/test.db, write the ODBC config
-./test/run-tests.sh      # run the pyodbc suite, then cargo test
+./integration-tests/setup.sh       # build the driver, create the database, write the ODBC config
+./integration-tests/run-tests.sh   # run the pyodbc suite, then cargo test
 ```
 
-Both are run on every pull request. `./test/run-tests.sh --windows` additionally
-runs the same suite inside a Windows VM; see
-[windows/WINDOWS.md](windows/WINDOWS.md) for how to provision one.
+Both are run on every pull request. `run-tests.sh --windows` additionally runs
+the same suite inside a Windows VM; see
+[integration-tests/README.md](integration-tests/README.md) for what is covered
+and [integration-tests/windows/WINDOWS.md](integration-tests/windows/WINDOWS.md)
+for how to provision one.
 
 For the architecture, the conventions and the full testing reference, see
 [AGENTS.md](AGENTS.md).

integration-tests/README.md

@@ -0,0 +1,86 @@
+# Integration tests
+
+Everything that exercises the driver from outside the Rust crate: through real
+unixODBC on Linux, and through the real Windows Driver Manager in a VM.
+
+There is no service to start. SQLite is a file, and `rusqlite` links its own
+copy of it into the driver, so the whole suite runs on a bare runner in seconds.
+That is exactly why it gates every pull request while the Trino driver's
+equivalent cannot.
+
+```bash
+./integration-tests/setup.sh       # build the driver, create the database, write the ODBC config
+./integration-tests/run-tests.sh   # pyodbc through unixODBC, then cargo test
+```
+
+Both take `--help`.
+
+## Layout
+
+| Path | What it holds |
+|------|---------------|
+| `setup.sh`, `run-tests.sh` | Wrappers. The logic is in `scripts/` |
+| `scripts/lib.sh` | The paths and helpers both scripts share. Sourced, never executed |
+| `scripts/setup.sh` | Builds the driver, creates `test.db`, writes `odbc.ini` / `odbcinst.ini` |
+| `scripts/run-tests.sh` | Runs the suites |
+| `suites/create_test_db.sql` | The schema and rows every suite reads |
+| `suites/test_integration.py` | The pyodbc suite, run once per connection style |
+| `generated/` | Everything `setup.sh` writes. Gitignored |
+| `windows/` | The VM suite, its libvirt definitions, and [WINDOWS.md](windows/WINDOWS.md) |
+
+`generated/` is ignored rather than committed because all three files it holds
+name absolute paths: the driver's `.so`, the database. None of them survives
+being moved to another checkout, so a committed copy would be wrong for
+everyone but its author.
+
+## What gets run
+
+`run-tests.sh` runs the pyodbc suite **twice**, against the same database:
+
+- **DSN-less**, `Driver=...;Database=...`, which exercises this driver's own
+  connection-string parsing.
+- **Via a DSN**, `DSN=test_sqlite`, where the Driver Manager resolves the
+  keywords out of `odbc.ini` first.
+
+They are separate runs because they fail separately. A driver that reads its
+parameters correctly can still be unreachable through a DSN, and that is a
+configuration most applications actually use.
+
+It then runs `cargo test`, so that one command gives a developer the whole
+suite. CI passes `--skip-cargo-test`, since its pre-commit job has already run
+exactly that via the `cargo-test` hook.
+
+## Options
+
+| Flag | Effect |
+|------|--------|
+| `--skip-build` | Reuse the driver already built. Forwarded to `windows_test.py`, whose build is a separate cross-compile |
+| `--skip-cargo-test` | Run the pyodbc suites only. What CI passes |
+| `--windows` | Additionally run the suite inside the Windows VM |
+
+Any other argument is forwarded to `windows_test.py` (`--host`, `--gateway`,
+`--user`, `--password`) and so is rejected without `--windows`: a flag
+forwarded to a script that never runs is a flag silently ignored.
+
+## Windows
+
+`windows/windows_test.py` deploys the cross-compiled DLL to a provisioned
+libvirt VM over WinRM, registers it, and runs the same
+`suites/test_integration.py` through the Windows Driver Manager, DSN-less and
+then via a DSN. The Windows DM is much stricter than unixODBC and tends to fail
+silently, so this is measured rather than assumed.
+
+See [windows/WINDOWS.md](windows/WINDOWS.md) for provisioning the VM.
+
+## Interactively
+
+`setup.sh` prints these at the end:
+
+```bash
+export ODBCSYSINI=integration-tests/generated
+export ODBCINI=integration-tests/generated/odbc.ini
+isql -3 test_sqlite -v
+```
+
+Prefix either with `ODBC_LOG_LEVEL=debug` to see which ODBC functions your
+client calls, and in what order.

integration-tests/generated/.gitignore

@@ -0,0 +1,4 @@
+# Everything setup.sh writes here embeds absolute paths, so none of it is
+# portable between checkouts. Keep the directory, ignore the contents.
+*
+!.gitignore

integration-tests/run-tests.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Wrapper. The logic lives in scripts/run-tests.sh.
+exec "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scripts/run-tests.sh" "$@"

integration-tests/scripts/lib.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Shared paths and helpers. Sourced, never executed.
+#
+# SC2034: every variable below is consumed by a script that sources this file,
+# which shellcheck cannot see from here.
+# shellcheck disable=SC2034
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+PROJECT_DIR="$(cd "$TEST_DIR/.." && pwd)"
+
+SUITES_DIR="$TEST_DIR/suites"
+WINDOWS_DIR="$TEST_DIR/windows"
+
+# Everything setup.sh writes lands here, and the whole directory is gitignored:
+# all three files embed absolute paths, so none of them is portable between
+# checkouts.
+GENERATED="$TEST_DIR/generated"
+DB_PATH="$GENERATED/test.db"
+ODBC_INI="$GENERATED/odbc.ini"
+ODBCINST_INI="$GENERATED/odbcinst.ini"
+
+DRIVER_PATH="$PROJECT_DIR/target/debug/libstackable_odbc_sqlite.so"
+
+# The DSN setup.sh writes into odbc.ini, and the one run-tests.sh connects
+# through for its second configuration.
+DSN_NAME="test_sqlite"
+
+mkdir -p "$GENERATED"
+
+# Point unixODBC at the generated configuration rather than the system's.
+# ODBCSYSINI is a *directory* (unixODBC appends `odbcinst.ini` itself) while
+# ODBCINI is a full path, which is why the two are not spelled alike.
+use_generated_odbc_config() {
+    export ODBCSYSINI="$GENERATED"
+    export ODBCINI="$ODBC_INI"
+}
+
+# Build the cdylib pyodbc loads. `cargo test` builds the test harness, not this,
+# so a run that skips it would silently exercise the previous build. cargo is
+# incremental, so repeating it costs nothing when nothing changed.
+build_driver() {
+    echo "=== Building stackable-odbc-sqlite ==="
+    (cd "$PROJECT_DIR" && cargo build)
+}
+
+# usage <script>. Prints the contiguous comment block below the shebang, minus
+# the leading `# `, as that script's help text. Derived rather than given as a
+# line range, which silently truncates the moment a line is added to the header.
+usage() {
+    awk 'NR > 1 && /^#/ { sub(/^# ?/, ""); print; next } NR > 1 { exit }' "$1"
+}
+
+require_setup() {
+    if [[ ! -f "$DB_PATH" || ! -f "$ODBC_INI" ]]; then
+        echo "ERROR: $GENERATED is incomplete. Run ./integration-tests/setup.sh first." >&2
+        exit 1
+    fi
+}