Merge pull request #25507 from fidelity-contributions/issue-25352-dryrun-testing-section

Issue 25352 dryrun testing section

docs/features/software-templates/dry-run-testing.md

@@ -0,0 +1,79 @@
+---
+id: dry-run-testing
+title: Dry Run Testing
+description: How to enable and implement dry run testing in actions
+---
+
+Scaffolder templates can be tested using the dry run feature of scaffolder actions. This allows you to simulate the effects of running a scaffolder action without making any actual changes to your environment, for example creating a webhook in Github. Once dry run is enabled in the scaffolder action, you can add handling to actions you use in your scaffolder templates to define how an action should operate in a dry run scenario.
+
+## Enabling dry run testing
+
+To enable dry run for your scaffolder action you need to add `supportsDryRun: true` to the configuration object of `createTemplateAction` in the function where the behavior of your action is defined:
+
+```typescript
+export function exampleAction() {
+  return createTemplateAction<{
+    example: string;
+  }>({
+    id: 'action:example',
+    description: 'Example action',
+    schema: {
+      input: {
+        type: 'object',
+        properties: {
+          example: {
+            title: 'example',
+            type: 'string',
+          },
+        },
+      },
+    },
+    supportsDryRun: true,
+    async handler(ctx) {
+      ...
+    },
+  });
+}
+```
+
+## Adding handling for dry run
+
+To add handling for dry run functionality you need to add a check for `ctx.isDryRun` inside the handler of the configuration object which is being passed into `createTemplateAction` in the function where the behavior of your action is defined. Once the check is successful, you can perform the desired actions expected in a dry run, e.g. outputting non-sensitive inputs.
+
+```typescript
+async handler(ctx) {
+      ...
+
+      // If this is a dry run, log and return
+      if (ctx.isDryRun) {
+        ctx.logger.info(`Dry run complete`);
+        return;
+      }
+
+      ...
+    },
+```
+
+## Testing dry run handling
+
+You will also need to add tests for the dry run handling, for example:
+
+```typescript
+  it('should not perform action during dry run', async () => {
+    ...
+
+    // Create the context object with the necessary properties for a dry run
+    const ctx = {
+      ...mockContext,
+      isDryRun: true,
+      input: {
+        ...
+      },
+    };
+
+    // Call the handler with the context
+    await action.handler(ctx);
+
+    expect(...);
+  });
+```

microsite/sidebars.json

@@ -121,7 +121,8 @@
           "features/software-templates/writing-custom-step-layouts",
           "features/software-templates/authorizing-scaffolder-template-details",
           "features/software-templates/migrating-to-rjsf-v5",
-          "features/software-templates/migrating-from-v1beta2-to-v1beta3"
+          "features/software-templates/migrating-from-v1beta2-to-v1beta3",
+          "features/software-templates/dry-run-testing"
         ]
       },
       {

mkdocs.yml

@@ -64,6 +64,7 @@ nav:
           - Writing Custom Actions: 'features/software-templates/writing-custom-actions.md'
           - Writing Custom Step Layouts: 'features/software-templates/writing-custom-step-layouts.md'
           - Migrating from v1beta2 to v1beta3 templates: 'features/software-templates/migrating-from-v1beta2-to-v1beta3.md'
+          - Dry Run Testing: 'features/software-templates/dry-run-testing.md'
       - Backstage Search:
           - Overview: 'features/search/README.md'
           - Getting Started: 'features/search/getting-started.md'