Run and debug Golem Scala SDK integration tests. Use when running golem-scala integration tests, debugging test failures, or working with GolemExamplesIntegrationSpec.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Run and debug Golem Scala SDK integration tests. Use when running golem-scala integration tests, debugging test failures, or working with GolemExamplesIntegrationSpec.
Golem Scala Integration Tests
Integration tests for the Golem Scala SDK live in sdks/scala/integration-tests/. They exercise test agents against a real local Golem server.
Prerequisites
golem-cli on PATH (v1.5.0-dev at ~/.cargo/bin/golem-cli)
TS packages built — the Golem TypeScript SDK packages at the path pointed to by GOLEM_TS_PACKAGES_PATH
Port 9881 free — the test suite starts its own Golem server
SDK published locally — run from sdks/scala/:
cd sdks/scala
sbt '++3.8.2; set ThisBuild / version := "0.0.0-SNAPSHOT"; set ThisBuild / packageDoc / publishArtifact := false; set every (publish / skip) := false; modelJVM/publishLocal; modelJS/publishLocal; macros/publishLocal; core/publishLocal'
Running Tests
The simplest way to run all tests (unit + integration, Scala 2 + 3) is with non-client sbt:
cd sdks/scala
GOLEM_TS_PACKAGES_PATH=<TS_PACKAGES_PATH> sbt golemTestAll
The GOLEM_TS_PACKAGES_PATH env var is forwarded automatically by build.sbt to javaOptions and envVars for the integration tests.
Running specific tests with sbt --client
With sbt --client, env vars don't propagate to the forked test JVM. Use the override instead:
set
cd sdks/scala
# All integration tests
sbt --client '++3.8.2; set integrationTests / Test / javaOptions += "-Dgolem.tsPackagesPath=<TS_PACKAGES_PATH>"; integrationTests/test'# Only HTTP endpoint tests
sbt --client '++3.8.2; set integrationTests / Test / javaOptions += "-Dgolem.tsPackagesPath=<TS_PACKAGES_PATH>"; integrationTests/testOnly -- -t http-'# A specific test by name
sbt --client '++3.8.2; set integrationTests / Test / javaOptions += "-Dgolem.tsPackagesPath=<TS_PACKAGES_PATH>"; integrationTests/testOnly -- -t sync-return'
Use the sbt logging pattern (redirect to log file, check exit code).
Test Architecture
Server Lifecycle
The GolemServer.layer (ZLayer) handles everything:
Checks golem-cli is on PATH
Checks GOLEM_TS_PACKAGES_PATH / golem.tsPackagesPath is set
Verifies port 9881 is free (fails if already in use — kill any running golem server first)
Cleans golem-temp/ directory (stale REPL caches)
Starts golem-cli -vvv server run --clean --disable-app-manifest-discovery
Waits for port 9881 to accept connections (60s timeout)
Runs golem-cli deploy (with one retry)
On teardown: kills the server process tree
Two Test Categories
Sample tests — TypeScript REPL scripts in sdks/scala/test-agents/samples/*/repl-*.ts. Each script is executed via golem-cli repl scala:examples --language typescript --script-file <script>. Output is checked for expected fragments.
HTTP endpoint tests — Direct HTTP calls to localhost:9006 (configured in golem.yaml). Test code-first HTTP routes defined via @agentDefinition(mount=...) and @endpoint(...).
These are independent. REPL tests use golem-cli repl with TS scripts. HTTP tests use direct HTTP calls to port 9006.
deleteRecursive destroying files in external repos
The golem-temp/repl/ts/node_modules/@golem/ contains symlinks to the TS SDK packages directory. The cleanup code in GolemServer.layer checks for symlinks before recursing to avoid deleting symlink targets. Never use plain rm -rf on golem-temp/ — always delete symlinks first:
find sdks/scala/test-agents/golem-temp -type l -delete 2>/dev/null
rm -rf sdks/scala/test-agents/golem-temp
Verifying Agent Schemas
After deploy, inspect the component to verify constructor and method schemas:
golem-cli component get scala:examples --local
Look for correct parameter names in the output, e.g.:
WeatherAgent.getWeather(city: string) — not (value: string)
CatalogAgent(region: string, catalog: string) — case class fields flattened
