From 3c03ba01999e6a4cd37919e72e4b17e827bea0b3 Mon Sep 17 00:00:00 2001 From: Hampus Lavin Date: Tue, 26 Nov 2024 16:06:12 +0100 Subject: [PATCH] docs: add upgrade to 2.2 page (#217) --- .markdownlint.yaml | 3 +- .../04-upgrade-to-two-point-two.md | 184 ++++++++++++++++++ 2 files changed, 186 insertions(+), 1 deletion(-) create mode 100644 docs/08-upgrading/04-upgrade-to-two-point-two.md diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 6906fcd..4ac721b 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,4 +1,5 @@ MD001: false MD013: false MD014: false -MD024: false \ No newline at end of file +MD024: false +MD033: false # Allow inline HTML \ No newline at end of file diff --git a/docs/08-upgrading/04-upgrade-to-two-point-two.md b/docs/08-upgrading/04-upgrade-to-two-point-two.md new file mode 100644 index 0000000..807e2d2 --- /dev/null +++ b/docs/08-upgrading/04-upgrade-to-two-point-two.md @@ -0,0 +1,184 @@ +# Upgrade to 2.2 + +Serverpod 2.2 includes new test tools that make it easy to create tests for endpoint methods. For new projects they are configured by default, but existing projects need to go through some steps to enable it (see below). The full documentation of this feature can also be found [here](../concepts/testing/get-started). + +## Add test tools to existing projects + +For existing non-Mini projects, a few extra things need to be done: + +1. Add the `server_test_tools_path` key with the value `test/integration/test_tools` to `config/generator.yaml`: + +```yaml +server_test_tools_path: test/integration/test_tools +``` + + Without this key, the test tools file is not generated. With the above config the location of the test tools file is `test/integration/test_tools/serverpod_test_tools.dart`, but this can be set to any folder (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: + +```yaml +# Add to the existing services +postgres_test: + image: postgres:16.3 + ports: + - '9090:5432' + environment: + POSTGRES_USER: postgres + POSTGRES_DB: _test + POSTGRES_PASSWORD: "" + volumes: + - _test_data:/var/lib/postgresql/data + profiles: + - '' # Default profile + - test +redis_test: + image: redis:6.2.6 + ports: + - '9091:6379' + command: redis-server --requirepass "" + environment: + - REDIS_REPLICATION_MODE=master + profiles: + - '' # Default profile + - test +volumes: + # ... + _test_data: +``` + +
+Or copy the complete file here. +

+ +```yaml +services: + # Development services + postgres: + image: postgres:16.3 + ports: + - '8090:5432' + environment: + POSTGRES_USER: postgres + POSTGRES_DB: + POSTGRES_PASSWORD: "" + volumes: + - _data:/var/lib/postgresql/data + profiles: + - '' # Default profile + - dev + redis: + image: redis:6.2.6 + ports: + - '8091:6379' + command: redis-server --requirepass "" + environment: + - REDIS_REPLICATION_MODE=master + profiles: + - '' # Default profile + - dev + + # Test services + postgres_test: + image: postgres:16.3 + ports: + - '9090:5432' + environment: + POSTGRES_USER: postgres + POSTGRES_DB: _test + POSTGRES_PASSWORD: "" + volumes: + - _test_data:/var/lib/postgresql/data + profiles: + - '' # Default profile + - test + redis_test: + image: redis:6.2.6 + ports: + - '9091:6379' + command: redis-server --requirepass "" + environment: + - REDIS_REPLICATION_MODE=master + profiles: + - '' # Default profile + - test + +volumes: + _data: + _test_data: +``` + +

+
+3. Create a `test.yaml` file and add it to the `config` directory: + +```yaml +# This is the configuration file for your 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. To set up your server, you will +# 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. + +# Configuration for the main API test server. +apiServer: + port: 0 + publicHost: localhost + publicPort: 0 + publicScheme: http + +# Configuration for the Insights test server. +insightsServer: + port: 0 + publicHost: localhost + publicPort: 0 + publicScheme: http + +# Configuration for the web test server. +webServer: + port: 0 + publicHost: localhost + publicPort: 0 + publicScheme: http + +# This is the database setup for your test server. +database: + host: localhost + port: 9090 + name: _test + user: postgres + +# This is the setup for your Redis test instance. +redis: + enabled: false + host: localhost + port: 9091 +``` + + +4. Add this entry to `config/passwords.yaml` + +```yaml +test: + database: '' + redis: '' +``` + + +5. Add a `dart_test.yaml` file to the `server` directory (next to `pubspec.yaml`) with the following contents: + +```yaml +tags: + integration: {} + +``` + + +6. Finally, add the `test` and `serverpod_test` packages as dev dependencies in `pubspec.yaml`: + +```yaml +dev_dependencies: + serverpod_test: # Should be same version as the `serverpod` package + test: ^1.24.2 +``` + +That's it, the project setup should be ready to start using the test tools!