Merge pull request #24074 from parmar-abhinav/master-yeoman

Add examples for run:yeoman scaffolder action and improve related tests

.changeset/wet-buttons-buy.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend-module-yeoman': minor
+---
+
+Add examples for `run:yeoman` scaffolder action.

plugins/scaffolder-backend-module-yeoman/package.json

@@ -45,6 +45,7 @@
     "@backstage/plugin-scaffolder-node-test-utils": "workspace:^",
     "@backstage/types": "workspace:^",
     "winston": "^3.2.1",
+    "yaml": "^2.0.0",
     "yeoman-environment": "^3.9.1"
   },
   "devDependencies": {

plugins/scaffolder-backend-module-yeoman/src/actions/run/yeoman.examples.test.ts

@@ -0,0 +1,115 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { yeomanRun } from './yeomanRun';
+
+jest.mock('./yeomanRun');
+
+import { createMockActionContext } from '@backstage/plugin-scaffolder-node-test-utils';
+import os from 'os';
+import { createRunYeomanAction } from './yeoman';
+import type { ActionContext } from '@backstage/plugin-scaffolder-node';
+import { JsonObject } from '@backstage/types';
+import yaml from 'yaml';
+import { examples } from './yeoman.examples';
+
+describe('run:yeoman', () => {
+  const mockTmpDir = os.tmpdir();
+
+  let mockContext: ActionContext<{
+    namespace: string;
+    args?: string[];
+    options?: JsonObject;
+  }>;
+
+  const action = createRunYeomanAction();
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+  });
+
+  it(`should ${examples[0].description}`, async () => {
+    const namespace = yaml.parse(examples[0].example).steps[0].input.namespace;
+    const input = yaml.parse(examples[0].example).steps[0].input;
+    mockContext = createMockActionContext({
+      input: input,
+      workspacePath: mockTmpDir,
+    });
+
+    await action.handler(mockContext);
+    expect(yeomanRun).toHaveBeenCalledWith(
+      mockTmpDir,
+      namespace,
+      undefined,
+      undefined,
+    );
+  });
+
+  it(`should ${examples[1].description}`, async () => {
+    const namespace = yaml.parse(examples[1].example).steps[0].input.namespace;
+    const input = yaml.parse(examples[1].example).steps[0].input;
+    const args: string[] = yaml.parse(examples[1].example).steps[0].input.args;
+    mockContext = createMockActionContext({
+      input: input,
+      workspacePath: mockTmpDir,
+    });
+
+    await action.handler(mockContext);
+    expect(yeomanRun).toHaveBeenCalledWith(
+      mockTmpDir,
+      namespace,
+      args,
+      undefined,
+    );
+  });
+
+  it(`should ${examples[2].description}`, async () => {
+    const namespace = yaml.parse(examples[2].example).steps[0].input.namespace;
+    const input = yaml.parse(examples[2].example).steps[0].input;
+    const options = yaml.parse(examples[2].example).steps[0].input.options;
+    mockContext = createMockActionContext({
+      input: input,
+      workspacePath: mockTmpDir,
+    });
+
+    await action.handler(mockContext);
+    expect(yeomanRun).toHaveBeenCalledWith(
+      mockTmpDir,
+      namespace,
+      undefined,
+      options,
+    );
+  });
+
+  it(`should ${examples[3].description}`, async () => {
+    const namespace = yaml.parse(examples[3].example).steps[0].input.namespace;
+    const input = yaml.parse(examples[3].example).steps[0].input;
+    const options = yaml.parse(examples[3].example).steps[0].input.options;
+    const args: string[] = yaml.parse(examples[1].example).steps[0].input.args;
+    mockContext = createMockActionContext({
+      input: input,
+      workspacePath: mockTmpDir,
+    });
+
+    await action.handler(mockContext);
+    expect(yeomanRun).toHaveBeenCalledWith(
+      mockTmpDir,
+      namespace,
+      args,
+      options,
+    );
+  });
+});

plugins/scaffolder-backend-module-yeoman/src/actions/run/yeoman.examples.ts

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { TemplateExample } from '@backstage/plugin-scaffolder-node';
+import yaml from 'yaml';
+
+export const examples: TemplateExample[] = [
+  {
+    description: 'Run a Yeoman generator with minimal options',
+    example: yaml.stringify({
+      steps: [
+        {
+          id: 'run:yeoman',
+          action: 'run:yeoman',
+          name: 'Running a yeoman generator',
+          input: {
+            namespace: 'node:app',
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description:
+      'Run a yeoman generator with arguments to pass on to Yeoman for templating',
+    example: yaml.stringify({
+      steps: [
+        {
+          id: 'run:yeoman',
+          action: 'run:yeoman',
+          name: 'Running a yeoman generator',
+          input: {
+            namespace: 'node:app',
+            args: ['arg1', 'arg2'],
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description:
+      'Run a yeoman generator with options to pass on to Yeoman for templating',
+    example: yaml.stringify({
+      steps: [
+        {
+          id: 'run:yeoman',
+          action: 'run:yeoman',
+          name: 'Running a yeoman generator',
+          input: {
+            namespace: 'node:app',
+            options: { option1: 'value1', option2: 'value2' },
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description: 'Run a yeoman generator with all options',
+    example: yaml.stringify({
+      steps: [
+        {
+          id: 'run:yeoman',
+          action: 'run:yeoman',
+          name: 'Running a yeoman generator',
+          input: {
+            namespace: 'node:app',
+            args: ['arg1', 'arg2'],
+            options: { option1: 'value1', option2: 'value2' },
+          },
+        },
+      ],
+    }),
+  },
+];

plugins/scaffolder-backend-module-yeoman/src/actions/run/yeoman.ts

@@ -17,6 +17,7 @@
 import { JsonObject } from '@backstage/types';
 import { createTemplateAction } from '@backstage/plugin-scaffolder-node';
 import { yeomanRun } from './yeomanRun';
+import { examples } from './yeoman.examples';
 
 /**
  * Creates a `run:yeoman` Scaffolder action.
@@ -35,6 +36,7 @@ export function createRunYeomanAction() {
   }>({
     id: 'run:yeoman',
     description: 'Runs Yeoman on an installed Yeoman generator',
+    examples,
     schema: {
       input: {
         type: 'object',

yarn.lock

@@ -8719,6 +8719,7 @@ __metadata:
     "@backstage/plugin-scaffolder-node-test-utils": "workspace:^"
     "@backstage/types": "workspace:^"
     winston: ^3.2.1
+    yaml: ^2.0.0
     yeoman-environment: ^3.9.1
   languageName: unknown
   linkType: soft