|
| 1 | +# Testing |
| 2 | + |
| 3 | +ServiceControl tests are designed to test different components and behaviors. This document outlines the tests in the repository and what they are meant to test. |
| 4 | + |
| 5 | +## Unit tests |
| 6 | + |
| 7 | +ServiceControl components have specific unit test projects verifying their behaviors and API. |
| 8 | + |
| 9 | +## Packaging tests |
| 10 | + |
| 11 | +Packaging tests check: |
| 12 | + |
| 13 | +- Folder structure and content of the [packaging process](packaging.md) output. |
| 14 | +- That packaged [assembly versions match](packaging.md#assembly-mismatches). |
| 15 | + |
| 16 | +## Installation engine tests |
| 17 | + |
| 18 | +Installation engine tests run partial installations and checks: |
| 19 | + |
| 20 | +- That the generated configuration is correct. |
| 21 | +- That transport and persistence are correctly extracted. |
| 22 | + |
| 23 | +## Persistence tests |
| 24 | + |
| 25 | +Persistence tests check assumptions at the persistence seam level by exercising each persister. |
| 26 | +For local setup details, see [Local Testing of Persistence Providers](testing-persistence.md). |
| 27 | + |
| 28 | +## Transport tests |
| 29 | + |
| 30 | +Transport tests are done by executing the transport test suite for each transport. |
| 31 | + |
| 32 | +## Acceptance tests |
| 33 | + |
| 34 | +Run ServiceControl full version and use the HTTP API to validate results. LearningTransport is used for all tests. |
| 35 | + |
| 36 | +### Windows prerequisite: register the event sources |
| 37 | + |
| 38 | +On Windows, every acceptance test fails on first run with: |
| 39 | + |
| 40 | +``` |
| 41 | +System.Security.SecurityException : The source ServiceControl was not found on computer ., |
| 42 | +but some or all event logs could not be searched. Inaccessible logs: Security. |
| 43 | +``` |
| 44 | + |
| 45 | +Setup registers a Windows event source, and checking whether one already exists enumerates every event log, including `Security`, which a process without administrator rights cannot read. |
| 46 | + |
| 47 | +Register both sources once, from an **elevated** PowerShell prompt: |
| 48 | + |
| 49 | +```powershell |
| 50 | +[System.Diagnostics.EventLog]::CreateEventSource('ServiceControl', 'Application') |
| 51 | +[System.Diagnostics.EventLog]::CreateEventSource('ServiceControl.Audit', 'Application') |
| 52 | +``` |
| 53 | + |
| 54 | +Use the .NET API as shown rather than `New-EventLog`, which is not available in PowerShell 7. Afterwards the tests run normally without elevation, because the lookup finds the registered source before it needs to read `Security`. |
| 55 | + |
| 56 | +## Multi-instance tests |
| 57 | + |
| 58 | +Multi-instance tests validate the interaction between different ServiceControl instances. ServiceControl instances are run in-memory in the same process. LearningTransport is used for all tests. |
| 59 | + |
| 60 | +## Container tests |
| 61 | + |
| 62 | +Container images generated for all builds are pushed to the [GitHub container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry). Once pushed, all images are tested by [spinning them all up for each supported transport](/src/container-integration-test/). |
| 63 | + |
| 64 | +Containers built by a PR and stored on GitHub Container Registry can be tested locally: |
| 65 | + |
| 66 | +1. [Authenticate to the GitHub Container Registry using a personal access token](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic). |
| 67 | + - Create a [classic token](https://github.com/settings/tokens). Select the scope for `read:packages` |
| 68 | + - Copy the newly created token text. |
| 69 | + - Run the following command in a terminal: |
| 70 | + ```shell |
| 71 | + docker login ghcr.io |
| 72 | + ``` |
| 73 | + you will be prompted for a username (your particular.net email) and a password (the token) |
| 74 | + - ensure that you get a successful login message. |
| 75 | + - Use `docker logout ghcr.io` once the following steps are complete and consider removing the token from github if its no longer needed |
| 76 | +2. In the terminal, navigate to [`/docs/test-ghcr-tag`](/docs/test/ghcr-tag). |
| 77 | +3. Edit the [`.env` file](/docs/test-ghcr-tag/.env) to specify the PR-based tag (in the form `pr-####`) to test. |
| 78 | +4. Run `docker compose up -d`. |
| 79 | +5. Services will be available at the following URLs: |
| 80 | + * [RabbitMQ Management](http://localhost:15672) (Login: `guest`/`guest`) |
| 81 | + * [RavenDB](http://localhost:8080) |
| 82 | + * [ServiceControl API](http://localhost:33333/api) |
| 83 | + * [Audit API](http://localhost:44444/api) |
| 84 | + * [Monitoring API](http://localhost:33633) |
| 85 | + * [ServicePulse (latest from Docker Hub)](http://localhost:9090) |
| 86 | +6. Tear down services using `docker compose down`. |
| 87 | + |
| 88 | +## Container tests using Aspire |
| 89 | + |
| 90 | +The [Particular.Aspire.Hosting.ServicePlatform](https://github.com/Particular/Particular.Aspire.Hosting.ServicePlatform) package integrates the Particular Platform with the Aspire hosting platform. This package configures environment variables to attach the platform. There is a single file apphost in [`test-ghcr-tag-aspire`](/docs/test-ghcr-tag-aspire) to start up serviceconrol from a prerelease container image. |
| 91 | + |
| 92 | +Containers built by a PR and stored on GitHub Container Registry can be tested locally: |
| 93 | + |
| 94 | +1. Set up your github container registry credentials as described in the [Container tests](#container-tests) section above. |
| 95 | +2. Make sure you have the [Aspire CLI installed](https://aspire.dev/get-started/install-cli/). |
| 96 | +3. Run `aspire update` to ensure that the testing AppHost file `docs/test-ghcr-tag-aspire/AppHost.cs` is running the latest aspire SDK and RabbitMQ integration package. |
| 97 | +4. Run `aspire run docs/test-ghcr-tag-aspire/AppHost.cs -- tag` to start the application, where `tag` is the PR-based tag (in the form `pr-####`) to test. If no tag is provided, it will default to the `latest` tag. |
| 98 | +5. Once running you can open the dashboard from the link in the terminal, this dashboard will provide the assigned ports for each service. |
| 99 | + * RabbitMQ Management (Login: `guest`/`guest`) |
| 100 | + * RavenDB |
| 101 | + * ServiceControl API |
| 102 | + * Audit API |
| 103 | + * Monitoring API |
| 104 | + * ServicePulse (latest from Docker Hub) |
| 105 | +6. Aspire will automatically tear down the application when you exit the CLI process. |
0 commit comments