[static] enable unit testing in Pulumi projects (#3288)

Signed-off-by: Mateusz Błażejewski <mateusz.blazejewski@digitalasset.com>

Author: mblaze-da

.pre-commit-config.yaml

@@ -50,7 +50,7 @@ repos:
         language: system
         entry: "scripts/fix-ts.py"
         types_or: [javascript, jsx, ts, tsx]
-        exclude: "/[.]prettierrc[.]cjs$"
+        exclude: "(/[.]prettierrc[.]cjs$|jest.config.ts$)"
       - id: pulumi_config
         name: check pulumi configs
         language: system

TESTING.md

@@ -23,8 +23,11 @@
     - [Handling Errors in Integration Tests](#handling-errors-in-integration-tests)
     - [Connecting external tools to the shared Canton instances](#connecting-external-tools-to-the-shared-canton-instances)
     - [Testing App Upgrades](#testing-app-upgrades)
-    - [Testing from a custom canton instance]
+    - [Testing from a custom canton instance](#testing-from-a-custom-canton-instance)
   - [Deployment Tests](#deployment-tests)
+    - [Helm checks](#helm-checks)
+    - [Pulumi tests](#pulumi-tests)
+    - [Pulumi state checks](#pulumi-state-checks)
 - [CI Without Approval](#ci-without-approval)
 
 # Testing in Splice
@@ -430,9 +433,47 @@ When writing or debugging Helm tests, it is often useful to run `helm unittest`
 This produces rendered yaml files under a local `.debug` folder
 that can be inspected to understand errors or determine the correct paths for assertions.
 
-### Pulumi checks
+### Pulumi tests
 
-Our pulumi checks are based on checked in `expected` files that need to be updated whenever the expected deployment state changes.
+We use [jest](https://jestjs.io/) for unit tests in Pulumi projects. With these tests we aim to cover
+more complex parts of the deployment implementation and resource definitions. To do the latter we
+recommend using techniques described [here](https://www.pulumi.com/docs/iac/guides/testing/unit/).
+These tests are meant to be fast as they are run both in CI and in pre-commit hooks.
+
+#### Running tests
+To run unit tests from all Pulumi projects run `make -C $SPLICE_ROOT cluster/pulumi/unit-test`.
+Any more specific run requires using NPM directly. To do that the following prerequisites must be met:
+1. build the Pulumi codebase `make -C $SPLICE_ROOT cluster/pulumi/build`
+1. navigate to the root package with `cd $SPLICE_ROOT/cluster/pulumi`
+
+To run all tests from one or more Pulumi projects execute the following command.
+```
+npm exec -- jest --selectProjects <project> [project]...
+```
+Specific suites are selected by passing one or more patterns as positional arguments. For example
+the following matches `$SPLICE_ROOT/cluster/pulumi/common/src/retries.test.ts` but also any suite
+that contains `retries` in its path.
+```
+npm exec -- jest retries
+```
+Lastly, individual tests can be filtered using the `--testNamePattern` or `-t` for short as shown
+in the following example:
+```
+npm exec -- jest -t "retry runs the action again if it fails with an exception"
+```
+All the above ways of filtering tests can be combined to achieve the desired run. More information
+on jest CLI can be found [here](https://jestjs.io/docs/cli). One might also opt for an IDE extension.
+
+#### Adding new tests
+A new test can be added to an existing `*.test.ts` file or to a new `<module>.test.ts` suite where
+`<module>.ts` contains the unit to be tested. These suite files lie next to the module files which
+they cover. Please see the [jest "getting started"](https://jestjs.io/docs/getting-started) guide
+for tips on how to write tests. The type definitions for jest come from the `@jest/globals`
+package usage of which is described [here](https://jestjs.io/docs/getting-started#type-definitions).
+
+### Pulumi state checks
+To make sure that the impact of changes in the Pulumi resource definitions is well understood we
+rely on checked in `expected` files that need to be updated whenever the expected deployment state changes.
 
 Please run `make cluster/pulumi/update-expected` whenever you intend to change Pulumi deployment scripts in a way that alters deployed state.
 Compare the diff of the resulting `expected` files to confirm that the changes are as intended.

cluster/pulumi/common/src/retries.test.ts

@@ -0,0 +1,26 @@
+// Copyright (c) 2024 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { afterAll, expect, jest, test } from '@jest/globals';
+
+import { retry } from './retries';
+
+// suppresses error logs from retry to get cleaner test output
+const consoleErrorMock = jest.spyOn(console, 'error').mockImplementation(() => {});
+afterAll(() => {
+  consoleErrorMock.mockRestore();
+});
+
+test('retry runs the action again if it fails with an exception', async () => {
+  let executionIndex = 0;
+  async function unreliableAction(): Promise<void> {
+    try {
+      if (executionIndex === 0) {
+        throw new Error('action failed');
+      }
+    } finally {
+      ++executionIndex;
+    }
+  }
+  await expect(retry('', 0, 1, unreliableAction)).resolves.toBeUndefined();
+  expect(executionIndex).toBe(2);
+});

cluster/pulumi/jest.config.ts

@@ -0,0 +1,20 @@
+// Copyright (c) 2024 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Config } from '@jest/types';
+import { createDefaultPreset } from 'ts-jest';
+import pkg from './package.json' with { type: 'json' };
+
+const config: Config.InitialOptions = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['<rootDir>/src/**/*.test.ts'],
+  projects: pkg.workspaces
+    .filter(workspace => !['observability'].includes(workspace))
+    .map(projectDir => ({
+      displayName: projectDir,
+      rootDir: projectDir,
+      transform: createDefaultPreset().transform,
+    })),
+};
+export default config;

cluster/pulumi/local.mk

@@ -18,10 +18,14 @@ $(dir)/clean:
 $(dir)/format: $(dir)/.build
 	cd $(@D) && npm run format:fix
 
+.PHONY: $(dir)/unit-test
+$(dir)/unit-test: $(dir)/.build
+	cd $(@D) && npm run test
+
 pulumi_projects ::= operator deployment gcp infra canton-network sv-runbook validator-runbook multi-validator cluster sv-canton validator1 splitwell
 
 .PHONY: $(dir)/test $(dir)/update-expected
-$(dir)/test: $(foreach project,$(pulumi_projects),$(dir)/$(project)/test)
+$(dir)/test: $(dir)/unit-test $(foreach project,$(pulumi_projects),$(dir)/$(project)/test)
 
 .PHONY: $(dir)/update-expected
 $(dir)/update-expected: $(foreach project,$(pulumi_projects),$(dir)/$(project)/update-expected)