Skip to content

docs: Rework the Testing section for 4.0 - #721

Open
developerjamiu wants to merge 19 commits into
mainfrom
concepts-phase3-section8-testing
Open

docs: Rework the Testing section for 4.0#721
developerjamiu wants to merge 19 commits into
mainfrom
concepts-phase3-section8-testing

Conversation

@developerjamiu

Copy link
Copy Markdown
Contributor

Summary

Section-by-section rework of the Testing concept pages for Serverpod 4.0, following Data & the database (#696), Web server (#711), Scheduling (#719), and Operations (#720). The section keeps its linear shape but splits reference material out of the walkthrough, and every claim was checked against the framework source.

Stacked on #720, so it targets that branch and shows only its own changes. GitHub retargets it to main once #720 merges.

Changes

  • Get started drops from 229 lines to 66. The collapsed "Serverpod 2.1 or earlier" block, which duplicated the upgrade guide near-verbatim, becomes a pointer to it. The page now opens by saying what the test tools do before the setup steps.
  • Writing tests (was "The basics") keeps the pieces every test uses: the session builder, simulated authentication, seeding, and the exceptions the tools throw.
  • Configuration is a new page holding every withServerpod option, so the reference table no longer interrupts a page being read top to bottom.
  • Advanced examples gains future-call testing and loses a section whose advice did nothing (see below).
  • Best practises becomes Best practices, matching the spelling used everywhere else in the docs.

Corrections

  • The Docker prerequisite is gone. A 4.0 project sets database.dataPath in config/test.yaml, so dart test starts its own PostgreSQL and the compose services are never contacted.
  • "Optimizing the number of database connections" claimed the Serverpod instance is created lazily by sessionBuilder.build(), and recommended moving build() into setUpAll to reduce connections. The instance is constructed when withServerpod is called and the connection opens in setUpAll regardless, so the workaround changed nothing.
  • The configuration table was missing serverDirectory, and presented applyMigrations, rollbackDatabase, and runtimeParametersBuilder as always available. Without a database they are not generated at all, so passing one is a compile error.
  • The flushEventQueue example passed a built Session where the generated API takes the session builder.
  • copyWith defaults were documented as fixed values; both parameters inherit from the builder they are called on.
  • The generated file does not re-export Serverpod's own types, so pages that use Session, Scope, or Constant now say where they come from.

Notes

  • Two renamed URLs (/concepts/testing/the-basics, /concepts/testing/best-practises) need redirects at the GA cutover; recorded with the rest of the redirect work.
  • Three framework issues surfaced while verifying and are worth filing separately: the serverpod_test doc comment for flushEventQueue has the same session/sessionBuilder error corrected here, the start-timeout message tells users to run docker compose up, and working-with-endpoints.md has a pre-existing broken link to this section.

@developerjamiu developerjamiu self-assigned this Jul 27, 2026
@developerjamiu developerjamiu added the documentation Improvements or additions to documentation label Jul 27, 2026
marcelomendoncasoares added a commit to marcelomendoncasoares/serverpod_docs that referenced this pull request Jul 27, 2026
Comment thread docs/06-concepts/08-testing/03-configuration.md Outdated
Comment thread docs/06-concepts/08-testing/01-get-started.md Outdated
Comment thread docs/06-concepts/08-testing/05-best-practices.md Outdated
Comment thread docs/06-concepts/08-testing/01-get-started.md Outdated

@Zfinix Zfinix left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two renamed URLs here, worth getting the redirects in with the rest.

Base automatically changed from concepts-phase3-section7-operations to main July 28, 2026 11:20
…on8-testing

# Conflicts:
#	docs/06-concepts/08-testing/03-advanced-examples.md
@developerjamiu
developerjamiu requested a review from Zfinix July 28, 2026 11:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants