From 54a0cc779b39f12aecb1c4e9439e18f2007ae83a Mon Sep 17 00:00:00 2001 From: Tavi Nolan Date: Mon, 24 Jun 2024 18:09:57 +0100 Subject: [PATCH 1/5] Creating dry run documentation Signed-off-by: Tavi Nolan --- docs/plugins/dry-run-testing.md | 135 ++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 136 insertions(+) create mode 100644 docs/plugins/dry-run-testing.md diff --git a/docs/plugins/dry-run-testing.md b/docs/plugins/dry-run-testing.md new file mode 100644 index 0000000000..18b7343920 --- /dev/null +++ b/docs/plugins/dry-run-testing.md @@ -0,0 +1,135 @@ +--- +id: dry run testing +title: Dry Run Testing +description: Documentation on 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(...); + }); +``` + +## Dry run via API call + +Dry run can be performed using the dry-run API, which allows the dry run to be completed in code. +This [command line script](https://github.com/backstage/backstage/blob/master/contrib/scaffolder/template-testing-dry-run.md) offers a way for you to do work with dry-run API. You run it against a running instance, either locally or remote, and use it like: + +```bash +scaffolder-dry http://localhost:7007/ template-directory values.yml output-directory +``` + +If you're using backend permissions, pass a front-end auth token from a current browser session via --token $FRONTEND_TOKEN. + +You can also query the dry run endpoint directly in code, for example: + +`dry-run.js` + +```javascript +const template = yaml.load( + await fs.readFile('path/to/templates/template.yaml', 'utf-8'), +); +const values = JSON.parse( + await fs.readFile('path/to/templates/template_values.json', 'utf-8'), +); + +// Prepare the request body +const body = { + template, + values, + directoryContents, +}; + +// Send the request to the dry-run endpoint +const response = await fetch( + 'http://localhost:7000/api/scaffolder/v2/dry-run', + { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + Authorization: 'Bearer ', // replace 'YOUR_API_KEY' with your actual API key + }, + body: JSON.stringify(body), + }, +); +``` + +`template_values.json` + +```json +{ + "example": "test", + "name": "helloworld" +} +``` + +In this example `template.yaml` is your template yaml file, `template_values.json` would be a json file containing key value pairs for your template inputs, and `directoryContents` is an array that is populated with objects representing the contents of a specified directory (e.g. the same directory where you have your template yaml). Each object in the array corresponds to a file within the directory and contains two properties; the name of the file and the content of the file, encoded in Base64. +This is needed if any other files were required by the actions your template is using. diff --git a/mkdocs.yml b/mkdocs.yml index b9f6d41d46..045238e97e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -139,6 +139,7 @@ nav: - URL Reader: 'plugins/url-reader.md' - Testing: - Testing with Jest: 'plugins/testing.md' + - Dry Run Testing: 'plugins/dry-run-testing.md' - Publishing: - Publish private: 'plugins/publish-private.md' - Add to Directory: 'plugins/add-to-directory.md' From 612d552e1c5543657621e913466708e68c86d0c3 Mon Sep 17 00:00:00 2001 From: Tavi Nolan Date: Tue, 23 Jul 2024 11:45:56 +0100 Subject: [PATCH 2/5] Updating changes based on review comments Signed-off-by: Tavi Nolan --- .../software-templates}/dry-run-testing.md | 12 +++++------- microsite/sidebars.json | 3 ++- mkdocs.yml | 2 +- 3 files changed, 8 insertions(+), 9 deletions(-) rename docs/{plugins => features/software-templates}/dry-run-testing.md (87%) diff --git a/docs/plugins/dry-run-testing.md b/docs/features/software-templates/dry-run-testing.md similarity index 87% rename from docs/plugins/dry-run-testing.md rename to docs/features/software-templates/dry-run-testing.md index 18b7343920..fb2de0f672 100644 --- a/docs/plugins/dry-run-testing.md +++ b/docs/features/software-templates/dry-run-testing.md @@ -1,14 +1,14 @@ --- id: dry run testing title: Dry Run Testing -description: Documentation on how to enable and implement dry run testing in actions +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: +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() { @@ -38,7 +38,7 @@ export function exampleAction() { ## 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. +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) { @@ -91,9 +91,7 @@ If you're using backend permissions, pass a front-end auth token from a current You can also query the dry run endpoint directly in code, for example: -`dry-run.js` - -```javascript +```javascript title="dry-run.js" const template = yaml.load( await fs.readFile('path/to/templates/template.yaml', 'utf-8'), ); @@ -115,7 +113,7 @@ const response = await fetch( method: 'POST', headers: { 'Content-Type': 'application/json', - Authorization: 'Bearer ', // replace 'YOUR_API_KEY' with your actual API key + Authorization: 'Bearer ', // replace 'FRONT_END_TOKEN' with your actual front-end auth token }, body: JSON.stringify(body), }, diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 075025afbb..2e1d74f739 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -120,7 +120,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" ] }, { diff --git a/mkdocs.yml b/mkdocs.yml index 045238e97e..3e8c7864c3 100644 --- a/mkdocs.yml +++ b/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: 'plugins/dry-run-testing.md' - Backstage Search: - Overview: 'features/search/README.md' - Getting Started: 'features/search/getting-started.md' @@ -139,7 +140,6 @@ nav: - URL Reader: 'plugins/url-reader.md' - Testing: - Testing with Jest: 'plugins/testing.md' - - Dry Run Testing: 'plugins/dry-run-testing.md' - Publishing: - Publish private: 'plugins/publish-private.md' - Add to Directory: 'plugins/add-to-directory.md' From e5e7d0501b538933b432384ab0725226ec50ce0d Mon Sep 17 00:00:00 2001 From: "Nolan, Tavi" Date: Tue, 23 Jul 2024 12:43:43 +0100 Subject: [PATCH 3/5] Update mkdocs.yml Signed-off-by: Nolan, Tavi --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 3e8c7864c3..707929d132 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,7 +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: 'plugins/dry-run-testing.md' + - Dry Run Testing: 'feature/software-templates/dry-run-testing.md' - Backstage Search: - Overview: 'features/search/README.md' - Getting Started: 'features/search/getting-started.md' From 0bb72c38f0ac8a19c26c0dee9af0ddc56fd610e6 Mon Sep 17 00:00:00 2001 From: "Nolan, Tavi" Date: Fri, 26 Jul 2024 12:00:06 +0100 Subject: [PATCH 4/5] Update dry-run-testing.md based on comments Signed-off-by: Nolan, Tavi --- .../software-templates/dry-run-testing.md | 56 +------------------ 1 file changed, 1 insertion(+), 55 deletions(-) diff --git a/docs/features/software-templates/dry-run-testing.md b/docs/features/software-templates/dry-run-testing.md index fb2de0f672..dfabad265e 100644 --- a/docs/features/software-templates/dry-run-testing.md +++ b/docs/features/software-templates/dry-run-testing.md @@ -1,5 +1,5 @@ --- -id: dry run testing +id: dry-run-testing title: Dry Run Testing description: How to enable and implement dry run testing in actions --- @@ -77,57 +77,3 @@ You will also need to add tests for the dry run handling, for example: expect(...); }); ``` - -## Dry run via API call - -Dry run can be performed using the dry-run API, which allows the dry run to be completed in code. -This [command line script](https://github.com/backstage/backstage/blob/master/contrib/scaffolder/template-testing-dry-run.md) offers a way for you to do work with dry-run API. You run it against a running instance, either locally or remote, and use it like: - -```bash -scaffolder-dry http://localhost:7007/ template-directory values.yml output-directory -``` - -If you're using backend permissions, pass a front-end auth token from a current browser session via --token $FRONTEND_TOKEN. - -You can also query the dry run endpoint directly in code, for example: - -```javascript title="dry-run.js" -const template = yaml.load( - await fs.readFile('path/to/templates/template.yaml', 'utf-8'), -); -const values = JSON.parse( - await fs.readFile('path/to/templates/template_values.json', 'utf-8'), -); - -// Prepare the request body -const body = { - template, - values, - directoryContents, -}; - -// Send the request to the dry-run endpoint -const response = await fetch( - 'http://localhost:7000/api/scaffolder/v2/dry-run', - { - method: 'POST', - headers: { - 'Content-Type': 'application/json', - Authorization: 'Bearer ', // replace 'FRONT_END_TOKEN' with your actual front-end auth token - }, - body: JSON.stringify(body), - }, -); -``` - -`template_values.json` - -```json -{ - "example": "test", - "name": "helloworld" -} -``` - -In this example `template.yaml` is your template yaml file, `template_values.json` would be a json file containing key value pairs for your template inputs, and `directoryContents` is an array that is populated with objects representing the contents of a specified directory (e.g. the same directory where you have your template yaml). Each object in the array corresponds to a file within the directory and contains two properties; the name of the file and the content of the file, encoded in Base64. -This is needed if any other files were required by the actions your template is using. From 9d6ad1eeb628f93029a1a97510068361490c5a8b Mon Sep 17 00:00:00 2001 From: "Nolan, Tavi" Date: Tue, 30 Jul 2024 14:26:33 +0100 Subject: [PATCH 5/5] Update mkdocs.yml file path Signed-off-by: Nolan, Tavi --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 707929d132..38b03fbbea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,7 +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: 'feature/software-templates/dry-run-testing.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'