Guidewire Local Dev Loop
Overview
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.
./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.
./gradlew test --tests "com.acme.policycenter.rules.UnderwritingIssueRuleTest"
./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:
./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
./gradlew test --tests "com.acme.policycenter.validation.HighValueAccountValidatorTest" --continuous
Error Handling
| Symptom | Cause | Solution |
|---|
| Code change "saved" but breakpoint fires on old line numbers | hot-reload silently failed (interface change, plugin registry edit) | restart runServer; do not chase phantom bugs |
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 productionguidewire-sdk-patterns — when local code calls Cloud API, the same client patterns applyguidewire-ci-cd-pipeline — promotion of locally-developed config through GCC slots; GUnit gates run there tooguidewire-core-workflow-a — PolicyCenter workflows that local dev cycles target
Resources
