feat: use surfpool by default for `anchor test`/`anchor localnet` commands by MicaiahReid · Pull Request #4106 · solana-foundation/anchor

MicaiahReid · 2025-12-03T16:55:19Z

This PR updates the behavior of the anchor test and anchor localnet commands to use Surfpool as the default validator.

As a safeguard in case this breaks tests for any users, we've kept the solana-test-validator codepaths for now. Users can continue use the test validator by using the --validator legacy flag.

Though Surfpool should start and deploy your protocol out of the box when testing, Surfpool's behavior can configured in the Anchor.toml as such:

[surfpool]
startup_wait = 100
shutdown_wait = 100
rpc_port = 8888
ws_port = 8889
host = "127.0.0.1"
online = true # runs surfpool in "online" mode, pulling mainnet data on the fly
datasource_rpc_url = "..." # configure the mainnet url for online mode
airdrop_addresses = ["pubkey1", "pubkey2"]
manifest_file_path = "./txtx.yml" # runbook manifest path
runbooks = ["deployment", "another-runbook"] # runbooks to execute at startup
block_production_mode = "clock" # configure how blocks are produced, by default creates a block every transaction
slot_time = 200 # configure slot time when in clock production mode
log_level = "info" # by default no logs, configure to output to a log file

Some notes:

a few changes have been made to the CI to support surfpool, including installing surfpool in CI, configuring some runbooks, and making minor tweaks to the tests
we've added the .surfpool file to the .gitignore produced by anchor init so that surfpool logs aren't muddying commits
by default, Surfpool is running offline (not pulling mainnet data), and is generating in-memory runbooks to deploy user's protocols
accounts being setup via the Anchor.toml's genesis fields, and Test.toml account/clone/account_dir fields are respected and deployed to surfpool

* wip * refactor: Simplify Surfpool configuration and enhance validator argument handling - Removed the SurfpoolConfig struct and related logic, simplifying the ValidatorType enum. - Updated the command processing to accept additional arguments for the validator. - Adjusted the localnet and test functions to handle Surfpool and Solana validators more effectively. - Improved logging management for Surfpool validator. * feat(cli): Enhance argument handling for Surfpool validator - Added support for additional arguments to be passed to the test runner and validator. - Updated command definitions to include `--args` and `--validator-args` options. - Improved handling of validator arguments in the `test` and `localnet` functions. - Ensured proper routing of arguments to Surfpool when no explicit validator arguments are provided. * refactor(cli): Update ValidatorType enum and streamline argument handling * feat(cli): Introduce Surfpool configuration with validator integration * feat(cli): enable tui startup to localnet and fix some typos * feat(cli): add runbooks startup check to wait for the deployment of the program then run the tests against the local environment * chore: remove debug print * refactor(cli): change flags to be compatible with surfpool cli, add the runbooks serialization struct to make a more robust verification when waiting for runbooks * fix(cli): Improve runbook execution handling to consider failures as completed * clean up runbook execution checking logic * augment surfpool config fields * remove `SURFPOOL_RPC_URL` const * `remote_rpc_url` -> `datasource_rpc_url` * use `DEFAULT_RPC_PORT` const * fix surfpool command * add/use workflow to install surfpool * specify surfpool cli version for CI * disable surfpool logs by default; allow configuring in anchor.toml * add timeout_minutes to setup surfpool * clean up action * allow too many arguments for localnet fn * bump surfpool version for CI * start surfpool instead of validator in ci * update run-test.sh * fix setup-surfpool cache * add `.surfpool` folder to gitignore for `anchor init` * fix: apply `--offline` flag by default for surfpool * only print message about surfpool logs if logs created * feat: add block production mode to Surfpool configuration * bump surfpool versions in CI * feat: add block production mode to surfpool config for ido-pool test * feat: add sleep functionality to log tests for improved reliability * fix: update program log messages to use dynamic identifiers for better clarity * fix: skip mut error test until LiteSVM issue is resolved * fix: update surfpool CLI version to 0.11.2 in workflow files * fix: refactor testValidateAssociatedToken calls to use confirmed commitment * fix: add surfpool block production mode configuration for errors test * fix: start surfpool in daemon mode for client/example test * fix: add block production mode configuration for surfpool for misc * lint * fix: add setup step for surfpool in reusable tests workflow * add sleep in run-test.sh to execute runbooks * disable check_surfpool call in run-test.sh --------- Co-authored-by: MicaiahReid <micaiahreid@gmail.com>

vercel · 2025-12-03T16:55:24Z

@BretasArthur1 is attempting to deploy a commit to the Solana Foundation Team on Vercel.

A member of the Team first needs to authorize it.

…nation logic

…l installation

acheroncrypto

custom-discriminator tests are broken after this change:

  1) custom-discriminator
       Instructions
         Integer:
     TransactionExpiredTimeoutError: Transaction was not confirmed in 30.00 seconds. It is unknown if it succeeded or failed. Check signature 2gam24YNpo61hDLpEy89XbP993U5iVpwqTT8hdXrS9zKdQXDL4Sp1k2cPygVxuo1TEkGHKRhPMTMxjzuf6y6F9Et using the Solana Explorer or CLI tools.

Same with idl tests (CI):

  1) New IDL
       Case conversion
         Works when instructions have no case conversion in IDL:
     Error: failed to send transaction: Transaction simulation failed: This program may not be used for executing instructions

acheroncrypto · 2025-12-11T15:06:56Z

tests/errors/tests/errors.ts

-  it("Emits a mut error", async () => {
+  // Skip until LiteSVM issue is resolved: https://github.com/LiteSVM/litesvm/issues/235
+  it.skip("Emits a mut error", async () => {


The issue seems fixed LiteSVM/litesvm#235

acheroncrypto · 2025-12-11T15:07:06Z

tests/errors/tests/errors.ts

+      // wait for logs to be captured
+      for (let i = 0; i < 20; i++) {
+        if (signature) {
+          break;
+        }
+        await sleep(100);
+      }


Why is this necessary?

acheroncrypto · 2025-12-11T15:08:50Z

tests/misc/tests/misc/misc.ts

-          },
-        });
+          })
+          .rpc({ commitment: "confirmed" });


Why is the confirmed commitment necessary here (and others)?

…mands (solana-foundation#4106) * feat(cli): add surfpool config and integration (#3) * wip * refactor: Simplify Surfpool configuration and enhance validator argument handling - Removed the SurfpoolConfig struct and related logic, simplifying the ValidatorType enum. - Updated the command processing to accept additional arguments for the validator. - Adjusted the localnet and test functions to handle Surfpool and Solana validators more effectively. - Improved logging management for Surfpool validator. * feat(cli): Enhance argument handling for Surfpool validator - Added support for additional arguments to be passed to the test runner and validator. - Updated command definitions to include `--args` and `--validator-args` options. - Improved handling of validator arguments in the `test` and `localnet` functions. - Ensured proper routing of arguments to Surfpool when no explicit validator arguments are provided. * refactor(cli): Update ValidatorType enum and streamline argument handling * feat(cli): Introduce Surfpool configuration with validator integration * feat(cli): enable tui startup to localnet and fix some typos * feat(cli): add runbooks startup check to wait for the deployment of the program then run the tests against the local environment * chore: remove debug print * refactor(cli): change flags to be compatible with surfpool cli, add the runbooks serialization struct to make a more robust verification when waiting for runbooks * fix(cli): Improve runbook execution handling to consider failures as completed * clean up runbook execution checking logic * augment surfpool config fields * remove `SURFPOOL_RPC_URL` const * `remote_rpc_url` -> `datasource_rpc_url` * use `DEFAULT_RPC_PORT` const * fix surfpool command * add/use workflow to install surfpool * specify surfpool cli version for CI * disable surfpool logs by default; allow configuring in anchor.toml * add timeout_minutes to setup surfpool * clean up action * allow too many arguments for localnet fn * bump surfpool version for CI * start surfpool instead of validator in ci * update run-test.sh * fix setup-surfpool cache * add `.surfpool` folder to gitignore for `anchor init` * fix: apply `--offline` flag by default for surfpool * only print message about surfpool logs if logs created * feat: add block production mode to Surfpool configuration * bump surfpool versions in CI * feat: add block production mode to surfpool config for ido-pool test * feat: add sleep functionality to log tests for improved reliability * fix: update program log messages to use dynamic identifiers for better clarity * fix: skip mut error test until LiteSVM issue is resolved * fix: update surfpool CLI version to 0.11.2 in workflow files * fix: refactor testValidateAssociatedToken calls to use confirmed commitment * fix: add surfpool block production mode configuration for errors test * fix: start surfpool in daemon mode for client/example test * fix: add block production mode configuration for surfpool for misc * lint * fix: add setup step for surfpool in reusable tests workflow * add sleep in run-test.sh to execute runbooks * disable check_surfpool call in run-test.sh --------- Co-authored-by: MicaiahReid <micaiahreid@gmail.com> * fix: Ensure proper quoting in cleanup calls and improve process termination logic * fix: Improve cleanup logic and enhance surfpool process management * fix: supply surfpool_config to cluster_url fn * fix(ci): ensure local bin path is added to GITHUB_PATH during Surfpool installation * ci: debug surfpool install * debug ci * ci: remove sudo from install --------- Co-authored-by: Arthur Bretas <158767751+BretasArthur1@users.noreply.github.com>

MicaiahReid added 2 commits December 3, 2025 11:56

fix: Ensure proper quoting in cleanup calls and improve process termi…

78234c2

…nation logic

fix: Improve cleanup logic and enhance surfpool process management

8ffc9a5

MicaiahReid changed the title ~~feat(cli): add surfpool config and integration (#3)~~ feat: use surfpool by default for anchor test/anchor localnet commands Dec 3, 2025

MicaiahReid added 5 commits December 3, 2025 12:06

fix: supply surfpool_config to cluster_url fn

a491813

fix(ci): ensure local bin path is added to GITHUB_PATH during Surfpoo…

5a74229

…l installation

ci: debug surfpool install

244f303

debug ci

0a47fc3

ci: remove sudo from install

ee86e05

jacobcreech approved these changes Dec 11, 2025

View reviewed changes

jacobcreech merged commit 70b7db9 into solana-foundation:master Dec 11, 2025
54 of 57 checks passed

acheroncrypto reviewed Dec 11, 2025

View reviewed changes

This was referenced Dec 12, 2025

ci: Upgrade Solana version to 3.0.0 #4121

Merged

Flaky bpf-upgradeable-state test #4134

Closed

acheroncrypto mentioned this pull request Jan 30, 2026

fix: fixed system-coder tests #4210

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: use surfpool by default for `anchor test`/`anchor localnet` commands#4106

feat: use surfpool by default for `anchor test`/`anchor localnet` commands#4106
jacobcreech merged 8 commits intosolana-foundation:masterfrom
txtx:surfpool

MicaiahReid commented Dec 3, 2025 •

edited

Loading

Uh oh!

vercel bot commented Dec 3, 2025

Uh oh!

Uh oh!

acheroncrypto left a comment

Uh oh!

acheroncrypto Dec 11, 2025

Uh oh!

acheroncrypto Dec 11, 2025

Uh oh!

acheroncrypto Dec 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

MicaiahReid commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Dec 3, 2025

Uh oh!

Uh oh!

acheroncrypto left a comment

Choose a reason for hiding this comment

Uh oh!

acheroncrypto Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

acheroncrypto Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

acheroncrypto Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MicaiahReid commented Dec 3, 2025 •

edited

Loading