OpenParable
Skip to content
← Back to skills

Build And Verify

Testing & Quality
build-and-verify

Build And Verify is an Agent Skill for testing & quality published in the timeplus-io/proton repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/timeplus-io/proton/blob/HEAD/.claude/skills/build-and-verify/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/build-and-verify, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Build & Verify

Binaries

BinaryPath (stripped, preferred)Fallback
Server / Clientbuild/programs/stripped/bin/protonbuild/programs/proton
Unit testsbuild/src/stripped/bin/unit_tests_dbmsbuild/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 changedRun 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 typeAdd this testGuide
C++ logic / data structuresgtest case in src/references/unit-testing.md
SQL behavior / streaming semanticsstateless .sql + .referencereferences/sql-testing.md
End-to-end streaming scenariosmoke YAML casereferences/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

TopicFile
Unit tests: options, writing gtest casesreferences/unit-testing.md
SQL tests: run, write, streaming patternsreferences/sql-testing.md
Smoke tests: probe setup, options, writing YAML casesreferences/smoke-testing.md
Materialized view testingreferences/mv-testing.md
JOIN testing patternsreferences/join-testing.md