documcp

Instructions

Implementation Reference

• src/tools/setup-playwright-tests.ts:75-306 (handler)

  The main handler function that implements the logic for setting up Playwright E2E tests, including generating config files, tests, Dockerfiles, GitHub Actions workflows, and updating package.json based on the SSG type.

  export async function setupPlaywrightTests(
    args: unknown,
  ): Promise<ToolResponse> {
    const {
      repositoryPath,
      ssg,
      projectName,
      mainBranch,
      includeAccessibilityTests,
      includeDockerfile,
      includeGitHubActions,
    } = inputSchema.parse(args);
  
    try {
      const config = SSG_CONFIGS[ssg];
      const templatesDir = path.join(__dirname, "../templates/playwright");
  
      // Create directories
      const testsDir = path.join(repositoryPath, "tests/e2e");
      await fs.mkdir(testsDir, { recursive: true });
  
      if (includeGitHubActions) {
        const workflowsDir = path.join(repositoryPath, ".github/workflows");
        await fs.mkdir(workflowsDir, { recursive: true });
      }
  
      // Read and process templates
      const filesCreated: string[] = [];
  
      // 1. Playwright config
      const configTemplate = await fs.readFile(
        path.join(templatesDir, "playwright.config.template.ts"),
        "utf-8",
      );
      const playwrightConfig = configTemplate.replace(
        /{{port}}/g,
        config.port.toString(),
      );
  
      await fs.writeFile(
        path.join(repositoryPath, "playwright.config.ts"),
        playwrightConfig,
      );
      filesCreated.push("playwright.config.ts");
  
      // 2. Link validation tests
      const linkTestTemplate = await fs.readFile(
        path.join(templatesDir, "link-validation.spec.template.ts"),
        "utf-8",
      );
      const linkTest = linkTestTemplate.replace(/{{projectName}}/g, projectName);
  
      await fs.writeFile(
        path.join(testsDir, "link-validation.spec.ts"),
        linkTest,
      );
      filesCreated.push("tests/e2e/link-validation.spec.ts");
  
      // 3. Accessibility tests (if enabled)
      if (includeAccessibilityTests) {
        const a11yTemplate = await fs.readFile(
          path.join(templatesDir, "accessibility.spec.template.ts"),
          "utf-8",
        );
  
        await fs.writeFile(
          path.join(testsDir, "accessibility.spec.ts"),
          a11yTemplate,
        );
        filesCreated.push("tests/e2e/accessibility.spec.ts");
      }
  
      // 4. Dockerfile (if enabled)
      if (includeDockerfile) {
        const dockerTemplate = await fs.readFile(
          path.join(templatesDir, "Dockerfile.template"),
          "utf-8",
        );
        const dockerfile = dockerTemplate
          .replace(/{{ssg}}/g, ssg)
          .replace(/{{buildCommand}}/g, config.buildCommand)
          .replace(/{{buildDir}}/g, config.buildDir);
  
        await fs.writeFile(
          path.join(repositoryPath, "Dockerfile.playwright"),
          dockerfile,
        );
        filesCreated.push("Dockerfile.playwright");
      }
  
      // 5. GitHub Actions workflow (if enabled)
      if (includeGitHubActions) {
        const workflowTemplate = await fs.readFile(
          path.join(templatesDir, "docs-e2e.workflow.template.yml"),
          "utf-8",
        );
        const workflow = workflowTemplate
          .replace(/{{mainBranch}}/g, mainBranch)
          .replace(/{{buildCommand}}/g, config.buildCommand)
          .replace(/{{buildDir}}/g, config.buildDir)
          .replace(/{{port}}/g, config.port.toString());
  
        await fs.writeFile(
          path.join(repositoryPath, ".github/workflows/docs-e2e-tests.yml"),
          workflow,
        );
        filesCreated.push(".github/workflows/docs-e2e-tests.yml");
      }
  
      // 6. Update package.json
      const packageJsonPath = path.join(repositoryPath, "package.json");
      let packageJson: any = {};
  
      try {
        const existing = await fs.readFile(packageJsonPath, "utf-8");
        packageJson = JSON.parse(existing);
      } catch {
        // Create new package.json
        packageJson = {
          name: projectName.toLowerCase().replace(/\s+/g, "-"),
          version: "1.0.0",
          private: true,
          scripts: {},
          dependencies: {},
          devDependencies: {},
        };
      }
  
      // Add Playwright dependencies
      packageJson.devDependencies = {
        ...packageJson.devDependencies,
        "@playwright/test": "^1.55.1",
        ...(includeAccessibilityTests
          ? { "@axe-core/playwright": "^4.10.2" }
          : {}),
      };
  
      // Add test scripts
      packageJson.scripts = {
        ...packageJson.scripts,
        "test:e2e": "playwright test",
        "test:e2e:ui": "playwright test --ui",
        "test:e2e:report": "playwright show-report",
        "test:e2e:docker":
          "docker build -t docs-test -f Dockerfile.playwright . && docker run --rm docs-test",
      };
  
      await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2));
      filesCreated.push("package.json (updated)");
  
      // 7. Create .gitignore entries
      const gitignorePath = path.join(repositoryPath, ".gitignore");
      const gitignoreEntries = [
        "test-results/",
        "playwright-report/",
        "playwright-results.json",
        "playwright/.cache/",
      ].join("\n");
  
      try {
        const existing = await fs.readFile(gitignorePath, "utf-8");
        if (!existing.includes("test-results/")) {
          await fs.writeFile(
            gitignorePath,
            `${existing}\n\n# Playwright\n${gitignoreEntries}\n`,
          );
          filesCreated.push(".gitignore (updated)");
        }
      } catch {
        await fs.writeFile(gitignorePath, `# Playwright\n${gitignoreEntries}\n`);
        filesCreated.push(".gitignore");
      }
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(
              {
                success: true,
                filesCreated,
                nextSteps: [
                  "Run `npm install` to install Playwright dependencies",
                  "Run `npx playwright install` to download browser binaries",
                  "Test locally: `npm run test:e2e`",
                  includeDockerfile
                    ? "Build container: `docker build -t docs-test -f Dockerfile.playwright .`"
                    : "",
                  includeGitHubActions
                    ? "Push to trigger GitHub Actions workflow"
                    : "",
                ].filter(Boolean),
                configuration: {
                  ssg,
                  buildCommand: config.buildCommand,
                  buildDir: config.buildDir,
                  port: config.port,
                  testsIncluded: {
                    linkValidation: true,
                    accessibility: includeAccessibilityTests,
                  },
                  integrations: {
                    docker: includeDockerfile,
                    githubActions: includeGitHubActions,
                  },
                },
              },
              null,
              2,
            ),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(
              {
                success: false,
                error: error.message,
              },
              null,
              2,
            ),
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/setup-playwright-tests.ts:20-28 (schema)

  Zod schema defining the input parameters for the tool, including repository path, SSG type, project name, and optional flags for accessibility tests, Dockerfile, and GitHub Actions.

  const inputSchema = z.object({
    repositoryPath: z.string().describe("Path to the documentation repository"),
    ssg: z.enum(["jekyll", "hugo", "docusaurus", "mkdocs", "eleventy"]),
    projectName: z.string().describe("Project name for tests"),
    mainBranch: z.string().optional().default("main"),
    includeAccessibilityTests: z.boolean().optional().default(true),
    includeDockerfile: z.boolean().optional().default(true),
    includeGitHubActions: z.boolean().optional().default(true),
  });