Golem Scala Integration Tests
Testing & Qualitygolem-scala-integration-testsGolem Scala Integration Tests is an Agent Skill for testing & quality published in the golemcloud/golem repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Run and debug Golem Scala SDK integration tests. Use when running golem-scala integration tests, debugging test failures, or working with GolemExamplesIntegrationSpec.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/golemcloud/golem/blob/HEAD/.agents/skills/golem-scala-integration-tests/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/golem-scala-integration-tests, 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.
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-clion 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 set override instead:
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-cliis on PATH - Checks
GOLEM_TS_PACKAGES_PATH/golem.tsPackagesPathis 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 viagolem-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 ingolem.yaml). Test code-first HTTP routes defined via@agentDefinition(mount=...)and@endpoint(...).
Key Files
| File | Purpose |
|---|---|
sdks/scala/integration-tests/src/test/scala/golem/integration/GolemExamplesIntegrationSpec.scala | All tests |
sdks/scala/test-agents/golem.yaml | App manifest (components, HTTP deployments) |
sdks/scala/test-agents/src/main/scala/example/minimal/ | Agent definitions and implementations |
sdks/scala/test-agents/samples/ | TypeScript REPL test scripts |
sdks/scala/test-agents/.golem/ | Build output (created by golem-cli deploy) |
sdks/scala/test-agents/.generated/agent_guest.wasm | Prebuilt QuickJS WASM runtime |
sdks/scala/test-agents/golem-temp/ | REPL caches, bridge SDKs (created at runtime) |
Before Running Tests
Kill existing golem processes
pkill -f "golem.*server" 2>/dev/null
Clean build artifacts when SDK code changed
rm -rf sdks/scala/test-agents/.golem sdks/scala/test-agents/target
rm -rf sdks/scala/macros/target sdks/scala/model/.jvm/target sdks/scala/model/.js/target
rm -rf sdks/scala/core/js/target
The Golem CLI caches builds aggressively ([UP-TO-DATE]). If you changed macro or core logic, you MUST delete .golem/ to force a rebuild.
Ensure .generated/agent_guest.wasm exists
cp sdks/scala/sbt/src/main/resources/golem/wasm/agent_guest.wasm sdks/scala/test-agents/.generated/agent_guest.wasm
This is normally done by sbt golemPrepare but the integration test deploy command needs it in place.
Common Failures
port 9881 is already in use
A golem server is already running. Kill it: pkill -f "golem.*server"
GOLEM_TS_PACKAGES_PATH env var or golem.tsPackagesPath system property must be set
Pass the system property via javaOptions in the sbt command (see Running Tests above).
Cannot find package '@golem/golem-ts-repl/index.js'
The TypeScript SDK packages are not built. Build them in sdks/ts/, or check the path is correct.
golem deploy failed after retry
Check the deploy output for the root cause. Common issues:
- Agent type discovery failure (JavaScript error during WASM initialization)
- Schema mismatch between mount path variables and constructor parameter names
- Missing
.generated/agent_guest.wasm
Build reported [UP-TO-DATE] but code changed
Delete sdks/scala/test-agents/.golem/ to force a full rebuild.
TypeScript REPL tests pass but HTTP tests fail (or vice versa)
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 flattenedInventoryAgent(arg0: string, arg1: number)— tuple positional names
Adding New Tests
HTTP endpoint test
- Define agent trait with
@agentDefinition(mount=...)and@endpoint(...)insdks/scala/test-agents/src/ - Add implementation class with
@agentImplementation() - Add agent to
sdks/scala/test-agents/golem.yamlunderhttpApi.deployments.local[0].agents - Add test in
GolemExamplesIntegrationSpec.scala:test("http-my-test") { for { _ <- ZIO.service[GolemServer] (status, body) <- httpGet("/api/my-agent/my-key/endpoint") } yield assertTrue(status == 200) && assertTrue(body.contains("expected")) } - Add to the appropriate test sequence and ensure it's included in the spec
TypeScript REPL test
- Create
sdks/scala/test-agents/samples/my-test/repl-my-test.ts - Register in the
sampleslist inGolemExamplesIntegrationSpec.scala - The manifest coverage test (
manifest covers all sample scripts) will fail if scripts exist without being registered