feat: Add e2e test documentation site with generation scripts and VitePress configuration.

[ShaileshParmar11]

This pull request introduces a robust, automated system for generating and maintaining up-to-date documentation for Playwright end-to-end (E2E) tests. The changes include a new documentation generator, workflow automation for both local development and CI, and updates to project configuration to support this workflow. The result is always-current, detailed E2E test documentation with minimal manual effort.

The most important changes are:

Automated Playwright Documentation Generation

• Added a custom documentation generator (generate.js and related tooling) that parses Playwright E2E test files, extracts test cases and steps, categorizes them by domain, and outputs comprehensive markdown documentation to playwright/docs. The generator uses Playwright's own test listing and the TypeScript compiler API for accurate extraction and metrics. [1] [2]

Workflow and CI Integration

• Introduced a GitHub Actions workflow (.github/workflows/playwright-docs-check.yml) that runs on pull requests affecting Playwright tests or documentation generator code. This workflow verifies if the documentation is up to date, auto-generates docs if necessary, and pushes fixes back to the PR branch, ensuring documentation never falls out of sync.
• Configured a pre-commit hook via .lintstagedrc.yaml to auto-run the documentation generator and stage changes whenever Playwright test files are modified locally, providing a first line of automation before CI.

Project Configuration and Documentation

• Updated package.json to add a generate:e2e-docs script for manual documentation generation.
• Added a detailed README.md in the doc-generator directory, explaining the architecture, usage, and automation workflow of the documentation system.
• Enhanced the main project README.md with a link to the generated E2E test documentation for greater visibility and discoverability.

Linting and Ignore Rules

• Updated .eslintignore to exclude the documentation generator directory from linting, and disabled the max-len rule for test files in .eslintrc.yaml to avoid unnecessary lint errors. [1] [2]

These changes collectively ensure that Playwright test documentation is always accurate, detailed, and automatically maintained as part of the development workflow.

[github-actions]

Jest test Coverage

UI tests summary

Lines	Statements	Branches	Functions
	64.12% (50631/78958)	41.6% (24565/59051)	45.13% (7758/17190)

[gitar-bot]

Code Review 👍 Approved with suggestions

Well-designed Playwright documentation generator with minor code quality and workflow concerns.

⚠️ Bug: Console log message appears before the operation it describes

📄 openmetadata-ui/src/main/resources/ui/playwright/doc-generator/generate.js

In generate.js, the console.log for "Staging generated docs..." is printed after the execSync('git add .') call. Looking at the grep results, it appears the log statements may be in the wrong order:

// 5. Stage files in Git
try {
  const { execSync } = require('child_process');
  console.log(`\n📦 Staging generated docs...`);  // This should come before execSync
  execSync('git add .', { cwd: OUTPUT_DIR, stdio: 'inherit' });
  console.log(`   ✓ git add completed for ${OUTPUT_DIR}`);
} catch (error) {
  console.error(`   ⚠️  Warning: Failed to stage files with git.`);
  console.error(error.message);
}

However, based on some grep outputs, there's a possibility the console.log and execSync calls are swapped/interleaved incorrectly. The user experience would be confusing if "Staging generated docs..." appears after completion. This could be a copy-paste or merge issue.

Suggested fix: Verify the order in the final file and ensure all console messages appear before their respective operations.

More details 💡 3 suggestions

💡 Code Quality: `execSync` should be required at top of file, not inside try block

📄 openmetadata-ui/src/main/resources/ui/playwright/doc-generator/generate.js

In generate.js, the require('child_process') is inside the try block for git staging:

try {
  const { execSync } = require('child_process');  // Should be at module top
  console.log(`\n📦 Staging generated docs...`);
  execSync('git add .', { cwd: OUTPUT_DIR, stdio: 'inherit' });

While this works, it's not idiomatic Node.js. The require should be at the top of the file with other requires for consistency and clarity. The same execSync is already used in playwright-loader.js where it's properly required at the top.

Suggested fix: Move the require to the top of the file:

const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

💡 Security: GitHub Actions workflow uses deprecated action version

📄 .github/workflows/playwright-docs-check.yml:74 🔗 GitHub Action releases page

The workflow file uses peter-evans/create-or-update-comment@v1 which is significantly outdated. The current stable version is v4. Using older action versions can introduce security risks as they may not have the latest security patches.

- name: Comment on PR
  if: steps.check_changes.outputs.changes_exist == 'true'
  uses: peter-evans/create-or-update-comment@v1  # Outdated

Suggested fix: Update to the latest stable version:

uses: peter-evans/create-or-update-comment@v4

Also consider pinning to a full SHA for supply-chain security.

💡 Edge Case: Temp config cleanup may fail silently on signal handlers

📄 openmetadata-ui/src/main/resources/ui/playwright/doc-generator/playwright-loader.js

In playwright-loader.js, the signal handler for cleanup calls process.exit() after cleanup():

const signalHandler = () => { cleanup(); process.exit(); };

If cleanup() throws an error (though it has a try/catch internally), the process will still exit. However, the registered exit listener behavior isn't fully tested:

• process.on('exit', cleanup) is registered but commented out concerns suggest uncertainty about its behavior
• The finally block handles normal execution, but edge cases with concurrent signal handling might leave the temp config file behind

While the temp file is in a controlled location and has a predictable name, orphaned files could accumulate over time in rare edge cases.

Suggested fix: Consider using try-finally patterns more consistently, or use a library like tmp or rimraf for safer temp file handling. At minimum, document the expected cleanup behavior.

What Works Well

• Comprehensive domain categorization: The DOMAIN_MAPPING provides excellent organization of tests into logical domains (Governance, Platform, Discovery, Observability, Integration)
• Dual automation approach: Combining pre-commit hooks with CI safety net ensures documentation stays in sync even when hooks are bypassed
• Zero new dependencies: Cleverly leverages existing project dependencies (playwright, typescript, dotenv)
• AST-based step extraction: Using TypeScript Compiler API to parse test.step() calls provides accurate scenario counts
• Clean separation of concerns: Clear split between generate.js (orchestrator), markdown.js (renderer), and playwright-loader.js (data provider)
• Robust test refactoring: Converting arrays to named objects in test files (e.g., entities, services) improves test readability and documentation output

Recommendations

• Update the deprecated GitHub Action (peter-evans/create-or-update-comment@v1 → @v4)
• Move the execSync require to the top of generate.js for consistency
• Review the console.log ordering in the git staging section
• Consider documenting the temp config cleanup behavior for edge cases

Options

Auto-apply is off Gitar will not commit updates to this branch.
✅ Code review is on Gitar will review this change.
Display: compact Hiding non-applicable rules.

Comment with these commands to change:

Auto-apply	✅ Code review	Compact
gitar auto-apply:on	gitar code-review:off	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | This comment will update automatically (Docs)}

[sonarqubecloud]

Quality Gate passed for 'open-metadata-ui'

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[chirag-madlani]

Not sure if we can just check on /playwright folder?
Also can we have on demande to force run this workflow when needed?

[chirag-madlani]

Which PR this will add comment? since it's running on main?

[ShaileshParmar11]

It will run agains each PR, If PR has playwright changes then it will update docs and push into PR.