fix: Add new configuration options, add example.

docs/06-concepts/18-testing/02-the-basics.md

@@ -7,7 +7,7 @@ The `withServerpod` helper provides a `sessionBuilder` that helps with setting u
 |Property|Type|Default|Description|
 |:-----|:-----|:---:|:-----|
 |`authentication`|`AuthenticationOverride?`|`AuthenticationOverride.unauthenticated()`|See section [Setting authenticated state](#setting-authenticated-state).|
-|`enableLogging`|`bool?`|`false`|Wether logging is turned on for the session.|
+|`enableLogging`|`bool?`|`false`|Whether logging is turned on for the session.|
 
 The `copyWith` method creates a new unique session builder with the provided properties. This can then be used in endpoint calls (see section [Setting authenticated state](#setting-authenticated-state) for an example).
 
@@ -127,11 +127,21 @@ The following optional configuration options are available to pass as a second a
 
 |Property|Type|Default|
 |:-----|:-----|:---:|
+|`applyMigrations`|`bool?`|`true`|
+|`enableSessionLogging`|`bool?`|`false`|
 |`rollbackDatabase`|`RollbackDatabase?`|`RollbackDatabase.afterEach`|
 |`runMode`|`String?`|`ServerpodRunmode.test`|
-|`enableSessionLogging`|`bool?`|`false`|
-|`applyMigrations`|`bool?`|`true`|
-|`testGroupTagsOverride`|`List<String>?`|`null`|
+|`serverpodLoggingMode`|`ServerpodLoggingMode?`|`ServerpodLoggingMode.normal`|
+|`serverpodStartTimeout`|`Duration?`|`Duration(seconds: 30)`|
+|`testGroupTagsOverride`|`List<String>?`|`['integration']`|
+
+### `applyMigrations`
+
+Whether pending migrations should be applied when starting Serverpod. Defaults to `true`.
+
+### `enableSessionLogging`
+
+Whether session logging should be enabled. Defaults to `false`.
 
 ### `rollbackDatabase` {#rollback-database-configuration}
 
@@ -228,17 +238,17 @@ In production, the transaction call will throw if any database exception happene
 
 The run mode that Serverpod should be running in. Defaults to `test`.
 
-### `enableSessionLogging`
+### `serverpodLoggingMode`
 
-Wether session logging should be enabled. Defaults to `false`.
+The logging mode used when creating Serverpod. Defaults to `ServerpodLoggingMode.normal`.
 
-### `applyMigrations`
+### `serverpodStartTimeout`
 
-Wether pending migrations should be applied when starting Serverpod. Defaults to `true`.
+The timeout to use when starting Serverpod, which connects to the database among other things. Defaults to `Duration(seconds: 30)`.
 
 ### `testGroupTagsOverride` {#test-group-tags-override-configuration}
 
-By default Serverpod test tools tags the `withServerpod` test group with `"integration"`. This is to provide a simple way to only run unit or integration tests. This property allows this tag to be overridden to something else. Defaults to `null` (i.e. no override).
+By default Serverpod test tools tags the `withServerpod` test group with `"integration"`. This is to provide a simple way to only run unit or integration tests. This property allows this tag to be overridden to something else. Defaults to `['integration']`.
 
 ## Test exceptions
 

docs/06-concepts/18-testing/03-advanced-examples.md

@@ -113,3 +113,37 @@ withServerpod('Given CommunicationExampleEndpoint', (sessionBuilder, endpoints)
   });
 });
 ```
+
+## Optimising number of database connections
+
+By default, Dart's test runner runs tests concurrently. The number of concurrent tests depends on the running hosts' available CPU cores. If the host has a lot of cores it could trigger a case where the number of connections to the database exceeeds the maximum connections limit set for the database, which will cause tests to fail.
+
+Each `withServerpod` call will lazily create its own Serverpod instance which will connect to the database. Specifically, the code that causes the Serverpod instance to be created is `sessionBuilder.build()`, which happens at the latest in an endpoint call if not called by the test before.
+
+If a test needs a session before the endpoint call (e.g. to seed the database), `sessionBuilder.build()` has to be called which then triggers a database connection attempt.
+
+If the max connection limit is hit, there are two options:
+
+- Raise the max connections limit on the database.
+- Build out the session in `setUp`/`setUpAll` instead of the top level scope:
+
+```dart
+withServerpod('Given example test', (sessionBuilder, endpoints) {
+  // Instead of this
+  var session = sessionBuilder.build();
+
+
+  // Do this to postpone connecting to the database until the test group is running
+  late Session session;
+  setUpAll(() {
+    session = sessionBuilder.build();
+  });
+  // ...
+});
+```
+
+:::info
+
+This case should be rare and the above example is not a recommended best practice unless this problem is anticipated, or it has started happening.
+
+:::