Configure local Guidewire development workflow with Guidewire Studio, Gosu debugging,
and hot reload capabilities.
Use when setting up development environment, configuring IDE, or optimizing dev workflow.
Trigger with phrases like "guidewire local dev", "guidewire studio setup",
"gosu development", "guidewire debugging", "configure guidewire ide".
Run a local InsuranceSuite instance and iterate on Gosu rule logic in seconds, not minutes. The single biggest productivity killer in Guidewire development is paying the 5–15 minute gradle runServer cold-start cost on every change because the developer does not know which edits hot-reload and which force a restart.
Three production problems this skill prevents:
Restart cascade — developer changes a Gosu rule, restarts runServer, waits 8 minutes, finds the rule was wrong, repeats. A full day disappears in restarts.
Silent stale code — Studio claims it hot-reloaded a class but the running JVM is still executing the old bytecode (common when interfaces change). Tests pass against stale code.
GUnit drift — unit tests for Gosu rules diverge from the rules themselves because the cycle to run a single test through Studio is too slow; developers stop writing them.
Prerequisites
JDK 17 (for Cloud release 202503+)
Guidewire Studio installed (IntelliJ-based, distributed by Guidewire)
Local InsuranceSuite configuration zone (PolicyCenter, ClaimCenter, or BillingCenter)
≥16 GB RAM on the dev machine — runServer + Studio + the JVM debug agent need headroom
Sample data loader configured for the chosen product (e.g., PersonalAuto for PC)
Instructions
Build the inner loop in this order. Every step targets one of the three productivity killers above.
1. Start runServer once, keep it warm
Cold start takes 5–15 minutes; treat it as a session investment.
# Start in dev mode with debug agent on 8088, leaves the server attached to the terminal
./gradlew runServer -Pdebug=true -PdebugPort=8088 -Dgw.servermode=dev
gw.servermode=dev enables the hot-reload paths inside the JVM. debugPort=8088 exposes the JDWP debug agent — attach IntelliJ to it once and leave it. Restart only when the what hot-reloads table below says you must.
2. What hot-reloads, what does not
Memorize this table — it determines whether the next edit costs 0 seconds or 8 minutes.
Change type
Hot-reload?
Action
Gosu method body in an existing class
yes
save in Studio; runServer detects via Reload Plugin
Gosu rule (entity, validation, UW) body
yes
save; rule fires on next entity event
New Gosu class added to an existing package
yes
save; class is picked up on first reference
Gosu interface signature change
no
restart runServer (binary-incompatible class load)
New Gosu plugin registered
no
restart runServer (plugin registry is built once at boot)
PCF (Page Configuration Format) layout edit
yes
save; refresh the browser
New PCF page added to the navigation
partial
restart usually; Reload Plugin sometimes works in dev mode
Database schema change (new column, new entity)
no
restart with gradle dropAndCreateDatabase runServer
Localization bundle
yes
save; refresh browser
Messaging destination / App Event plugin
no
restart (plugin registry)
config/server.xml or config/plugin/registry/*.xml
no
restart
When in doubt, trust the JVM, not Studio. Open the IntelliJ debugger, set a breakpoint on the changed method, trigger the code path, and confirm the breakpoint hits the new line numbers. Studio's "reloaded" status is informational, not authoritative.
3. Attach the IntelliJ debugger once per session
Run > Edit Configurations > + > Remote JVM Debug
Host: localhost
Port: 8088
Module classpath: <your-config-module>
Save → run with the bug icon
Once attached, breakpoints survive Gosu hot-reloads. The connection drops only on full runServer restart. Use conditional breakpoints (policy.totalPremium.compareTo(BigDecimal("10000")) > 0) for production-shaped data — never trust toy values.
4. GUnit cycle for rule TDD
Gosu rules are testable without a running server. GUnit tests run in seconds and should drive every non-trivial rule change.
# Run a single GUnit test class
./gradlew test --tests "com.acme.policycenter.rules.UnderwritingIssueRuleTest"
# Run all rule tests in a package, with continuous re-run on change
./gradlew test --tests "com.acme.policycenter.rules.*" --continuous
--continuous reruns the matching tests every time a file changes. Pair with the rule under test in a split editor — feedback loop drops to <5 seconds per save.
5. Sample data isolation per session
Every developer needs a deterministic fixture set, not whatever junk is in the shared dev database. Load a per-session sample at runServer start:
# Load the standard sample, then a project-specific overlay
./gradlew loadSampleData -PsampleData=default -PsampleData=acme-uat-fixtures runServer
Project-specific sample sets live in modules/configuration/test/data/ and are checked in. Treat the dev database as ephemeral — never store work-in-progress data only in it; it dies on the next dropAndCreateDatabase.
Output
A working local dev loop ships with all of the following:
gradle runServer running in dev mode with debugPort=8088 exposed; remote-debug connection attached from IntelliJ.
The hot-reload-vs-restart table internalized and applied — at least 80% of edits cost zero restart time.
A gradle test --continuous watcher running in a side terminal for GUnit-driven TDD on the current rule.
Sample data loaded from a checked-in fixture set, reproducible across team members.
A breakpoint validation habit: every non-trivial rule change is confirmed hot-reloaded by hitting a breakpoint in the new line, not by trusting Studio's reload indicator.
Examples
Example 1 — Pure rule edit, zero restart
1. Edit rule body in modules/configuration/gsrc/.../UnderwritingIssueRules.gs
2. Save (Ctrl-S)
3. Trigger the rule (issue a quote in the running PC instance)
4. Breakpoint hits the new line numbers; rule fires with new logic
5. Total time from save to confirmation: <10 seconds
Example 2 — Interface change, controlled restart
1. Modify interface in modules/configuration/gsrc/.../IPolicyCalculator.gs
2. Recognize this is in the no-hot-reload row of the table
3. Stop runServer (Ctrl-C); start ./gradlew runServer -Pdebug=true -PdebugPort=8088
4. Wait ~8 minutes; reattach debugger
5. Resume work — accept the cost rather than chasing phantom bugs from stale bytecode
Example 3 — TDD cycle on a new validation rule
# Terminal 1: continuous test runner
./gradlew test --tests "com.acme.policycenter.validation.HighValueAccountValidatorTest" --continuous
# Editor: write the failing test first, watch it fail in <5s
# Implement the rule, watch the test pass in <5s
# Commit when green; do not run the full server until the rule is locked
Error Handling
Symptom
Cause
Solution
Code change "saved" but breakpoint fires on old line numbers
gradle runServer hangs at Starting server for >20 min
full database rebuild from a recent schema change
check logs in logs/PolicyCenter.log; if schema migration is running, wait it out; if hung, dropAndCreateDatabase
GUnit test passes locally, fails in CI
dev database carries stale data the test depends on
tests must self-fixture (@Before loads needed entities); never trust ambient sample data
IntelliJ debugger drops every few minutes
runServer crashed and auto-restarted under a launcher
check logs/PolicyCenter.log for OOM; raise -Xmx in gradle.properties
Hot reload works on Day 1, stops working after a git pull
merged change touched the plugin registry without your local picking it up
restart; rebase pulls do not always invalidate the plugin cache
ClassCastException on a class you just edited
binary-incompatible change to a non-interface class (e.g., changed a public field type)
restart; field-type changes are interface-equivalent for the JVM
Breakpoint set in Gosu, never hits
the rule path is not actually exercised by the test action
verify in logs/PolicyCenter.log that the rule fired; common cause is rule conditions filtering out the test data
Studio shows red error markers everywhere after pulling main
dependency cache stale
./gradlew clean compileGosu (don't clean the whole project — it nukes runServer's database)
For deeper coverage (containerized dev environments, multi-developer shared servers, plugin debug logging, custom datasource hooks), see implementation guide and API reference.
See Also
guidewire-install-auth — once your local runServer integrates outbound to a Cloud tenant, auth layer applies the same as production
guidewire-sdk-patterns — when local code calls Cloud API, the same client patterns apply
guidewire-ci-cd-pipeline — promotion of locally-developed config through GCC slots; GUnit gates run there too
guidewire-core-workflow-a — PolicyCenter workflows that local dev cycles target
