build-and-verify - SKILL.md Agent Skill

name: build-and-verify description: Build, compile, run server/client/cluster, execute unit/stateless/SQL tests, verify results, and troubleshoot build/test failures. Make sure to use this skill whenever the user mentions building, compiling, ninja, cmake, running tests, test failures, starting the server, or pre-commit checks, even if they just say 'it doesn't build' or 'the test broke'.

Build & Verify

Binaries

Binary	Path (stripped, preferred)	Fallback
Server / Client	`build/programs/stripped/bin/proton`	`build/programs/proton`
Unit tests	`build/src/stripped/bin/unit_tests_dbms`	`build/src/unit_tests_dbms`

Stripped = 90 % smaller, faster startup, matches CI. Always prefer stripped; fall back only if the file does not exist.

Source-root rule — all build* dirs embed absolute source paths. Use each worktree's own build*; never share across checkouts.

Part 1 — Build

Always configure from inside the chosen build* directory with the repo's build.sh. Do not substitute direct cmake -S/-B configure commands unless the user explicitly requests that workflow.

cd build && ../build.sh Debug   # configure (once)
cd build && ninja                # incremental rebuild

Part 2 — Test

Full run (pre-commit)

./run-all-tests.sh                # unit → SQL → smoke (all three)
./run-all-tests.sh --skip-smoke   # faster pass: unit + SQL only
./run-all-tests.sh --only unit    # single suite: unit | sql | smoke
./run-all-tests.sh --port <tcp>   # reuse running server for SQL + smoke

Targeted run (during issue work)

What changed	Run this
C++ data structures / algorithms	`./run-unit-tests.sh <SuiteName>`
SQL parsing / planner / execution	`./run-sql-tests.sh <test_id>`
Streaming end-to-end behaviour	`./run-smoke-tests.sh -s <suite>`
Unsure	`./run-all-tests.sh --skip-smoke` then add smoke if behaviour changed

Individual scripts

All scripts auto-manage server lifecycle and accept --help.

# Unit (no server needed)
./run-unit-tests.sh                          # all
./run-unit-tests.sh StorageStream            # prefix filter → StorageStream*
./run-unit-tests.sh "ParserStream.ParseDDL"  # exact case
./run-unit-tests.sh -l StorageStream         # list, don't run

# Stateless SQL
./run-sql-tests.sh                           # all
./run-sql-tests.sh 00001_select_1            # single test
./run-sql-tests.sh '0003_*'                  # wildcard prefix
./run-sql-tests.sh --port <tcp> 0003_*       # reuse running server

# Smoke
./run-smoke-tests.sh                         # all suites
./run-smoke-tests.sh -s tumble_window        # single suite
./run-smoke-tests.sh -s tumble_window -k 00_tumble_window_max
./run-smoke-tests.sh --collect-only          # list, don't run
./run-smoke-tests.sh --port <tcp>            # reuse running server

Writing tests

Change type	Add this test	Guide
C++ logic / data structures	gtest case in `src/`	references/unit-testing.md
SQL behavior / streaming semantics	stateless `.sql` + `.reference`	references/sql-testing.md
End-to-end streaming scenario	smoke YAML case	references/smoke-testing.md

Server (manual start/stop)

Only needed when running SQL or smoke tests with --port / --reuse-server.

./start-local-proton.sh             # prints tcp: and table_http: ports
build/programs/stripped/bin/proton client --port <tcp>
kill $(cat tmp_data_<tcp>/proton.pid)      # stop by port

Runtime data and logs: ./tmp_data_<tcp>/ — removed automatically on exit when the test script started the server. When using --port/--reuse-server, the directory is left untouched. Test reports: tmp_data_<tcp>/logs/sql/ and tmp_data_<tcp>/logs/smoke/ (server-owned mode); ./tmp/sql_reports/ and ./tmp/smoke_logs/ (reuse mode).

Parallel-safe — each start-local-proton.sh picks a free port automatically; multiple instances (or concurrent agents) coexist without conflicts.

Debugging

# Running queries / stream state
build/programs/stripped/bin/proton client --port <tcp> \
  --query "SELECT * FROM system.processes"
build/programs/stripped/bin/proton client --port <tcp> --query "SHOW STREAMS"
build/programs/stripped/bin/proton client --port <tcp> --query "SHOW VIEWS"

# Server logs
tail -f ./tmp_data_<tcp>/data/var/log/proton-server/proton-server.log
tail -f ./tmp_data_<tcp>/data/var/log/proton-server/proton-server.err.log

References

Topic	File
Unit tests: options, writing gtest cases	references/unit-testing.md
SQL tests: run, write, streaming patterns	references/sql-testing.md
Smoke tests: probe setup, options, writing YAML cases	references/smoke-testing.md
Materialized view testing	references/mv-testing.md
JOIN testing patterns	references/join-testing.md