fix: add tag override, add new default folder (#186)

docs/06-concepts/18-testing/01-get-started.md

@@ -18,7 +18,7 @@ For Serverpod Mini projects, everything related to the database in this guide ca
 <summary> Have an existing project? Follow these steps first!</summary>
 <p>
 For existing non-Mini projects, a few extra things need to be done:
-1. Add the `server_test_tools_path` key to `config/generator.yaml`. Without this key, the test tools file is not generated. The default location for the generated file is `integration_test/test_tools/serverpod_test_tools.dart`, but this can be set to any path (though should be outside of `lib` as per Dart's test conventions).
+1. Add the `server_test_tools_path` key to `config/generator.yaml`. Without this key, the test tools file is not generated. The default location for the generated file is `test/integration/test_tools/serverpod_test_tools.dart`, but this can be set to any path (though should be outside of `lib` as per Dart's test conventions).
 
 2. New projects now come with a test profile in `docker-compose.yaml`. This is not strictly mandatory, but is recommended to ensure that the testing state is never polluted. Add the snippet below to the `docker-compose.yaml` file in the server directory:
 
@@ -114,33 +114,30 @@ volumes:
 3. Create a `test.yaml` file and add it to the `config` directory:
 
 ```yaml
-# This is the configuration file for your local test environment. By
-# default, it runs a single server on port 8090. To set up your server, you will
+# This is the configuration file for your local test environment. All ports are set to zero in this file which makes the server find the next available port. This is needed to enable running tests concurrently.
 # need to add the name of the database you are connecting to and the user name.
 # The password for the database is stored in the config/passwords.yaml.
-#
-# When running your server locally, the server ports are the same as the public
-# facing ports.
+
 
 # Configuration for the main API test server.
 apiServer:
-  port: 9080
+  port: 0
   publicHost: localhost
-  publicPort: 9080
+  publicPort: 0
   publicScheme: http
 
 # Configuration for the Insights test server.
 insightsServer:
-  port: 9081
+  port: 0
   publicHost: localhost
-  publicPort: 9081
+  publicPort: 0
   publicScheme: http
 
 # Configuration for the web test server.
 webServer:
-  port: 9082
+  port: 0
   publicHost: localhost
-  publicPort: 9082
+  publicPort: 0
   publicScheme: http
 
 # This is the database setup for your test server.
@@ -165,11 +162,19 @@ test:
   redis: '<insert redis test password>'
 ```
 
+5. Add a `dart_test.yaml` file to the `server` directory (next to `pubspec.yaml`) with the following contents:
+
+```yaml
+tags:
+  integration: {}
+
+```
+
 That's it, the project setup should be ready to start using the test tools!
 </p>
 </details>
 
-Go to the server directory and generate the test tools by running `serverpod generate --experimental-features testTools`. The default location for the generated file is `integration_test/test_tools/serverpod_test_tools.dart`. The folder name `integration_test` is chosen to differentiate from unit tests (see the [best practises section](best-practises#unit-and-integration-tests) for more information on this).
+Go to the server directory and generate the test tools by running `serverpod generate --experimental-features testTools`. The default location for the generated file is `test/integration/test_tools/serverpod_test_tools.dart`. The folder name `test/integration` is chosen to differentiate from unit tests (see the [best practises section](best-practises#unit-and-integration-tests) for more information on this).
 
 The generated file exports a `withServerpod` helper that enables you to call your endpoints directly like regular functions:
 
@@ -212,7 +217,7 @@ By default this starts up both the `development` and `test` profiles. To only st
 Now the test is ready to be run:
 
 ```bash
-dart test integration_test
+dart test
 ```
 
 Happy testing!

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

@@ -131,6 +131,7 @@ The following optional configuration options are available to pass as a second a
 |`runMode`|`String?`|`ServerpodRunmode.test`|
 |`enableSessionLogging`|`bool?`|`false`|
 |`applyMigrations`|`bool?`|`true`|
+|`testGroupTagsOverride`|`List<String>?`|`null`|
 
 ### `rollbackDatabase` {#rollback-database-configuration}
 
@@ -198,7 +199,7 @@ withServerpod(
 Additionally, when setting `rollbackDatabase.disabled`, it may also be needed to pass the `--concurrency=1` flag to the dart test runner. Otherwise multiple tests might pollute each others database state:
 
 ```bash
-dart test integration_test --concurrency=1
+dart test -t integration --concurrency=1
 ```
 
 For the other cases this is not an issue, as each `withServerpod` has its own transaction and will therefore be isolated.
@@ -235,6 +236,10 @@ Wether session logging should be enabled. Defaults to `false`.
 
 Wether pending migrations should be applied when starting Serverpod. Defaults to `true`.
 
+### `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).
+
 ## Test exceptions
 
 The following exceptions are exported from the generated test tools file and can be thrown by the test tools in various scenarios, see below.

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

@@ -1,5 +1,22 @@
 # Advanced examples
 
+## Run unit and integration tests separately
+
+To run unit and integration tests separately, the `"integration"` tag can be used as a filter. See the following examples:
+
+```bash
+# All tests (unit and integration)
+dart test
+
+# Only integration tests: add --tags (-t) flag
+dart test -t integration
+
+# Only unit tests: add --exclude-tags (-x) flag
+dart test -x integration
+```
+
+To change the name of this tag, see the [`testGroupTagsOverride`](the-basics#test-group-tags-override-configuration) configuration option.
+
 ## Test business logic that depends on `Session`
 
 It is common to break out business logic into modules and keep it separate from the endpoints. If such a module depends on a `Session` object (e.g to interact with the database), then the `withServerpod` helper can still be used and the second `endpoint` argument can simply be ignored:

docs/06-concepts/18-testing/04-best-practises.md

@@ -121,5 +121,5 @@ It is significantly easier to navigate a project if the different types of tests
 
 ✅ Have a clear structure for the different types of test. Serverpod recommends the following two folders in the `server`:
 
-- `test`: Unit tests.
-- `integration_test`: Tests for endpoints or business logic modules using the `withServerpod` helper.
+- `test/unit`: Unit tests.
+- `test/integration`: Tests for endpoints or business logic modules using the `withServerpod` helper.