Skip to main content

Contributing to Praman

Thank you for your interest in contributing to Praman — an AI-first SAP UI5 test automation platform for Playwright.

Development Setup

Prerequisites

  • Node.js 22+ (see .nvmrc for exact version)
  • npm (ships with Node.js)
  • Git

Getting Started

git clone https://github.com/mrkanitkar/playwright-praman.git
cd playwright-praman
npm install
npm run ci  # Validates full setup: lint + typecheck + test + build

Key Commands

CommandPurpose
npm run lintESLint (0 errors, 0 warnings)
npm run typecheckTypeScript type checking
npm run test:unitUnit tests (Vitest)
npm run test:unit:coverageUnit tests with coverage report
npm run buildProduction build (tsup, ESM + CJS)
npm run check:exportsValidate export map (attw)
npm run ciFull CI pipeline locally
npm run spellcheckSpell check (cspell)
npm run deadcodeDead code detection (knip)

Architecture

Layer 5: AI            — LLM-powered test generation
Layer 4: Fixtures      — Playwright fixture DI
Layer 3: Typed Proxy   — TypeScript control wrappers
Layer 2: Bridge        — Browser-based control discovery (page.evaluate)
Layer 1: Core          — Logging, config, errors, utilities

Sub-path exports: ., ./ai, ./intents, ./vocabulary, ./fe, ./reporters

Path aliases: #core/*, #bridge/*, #proxy/*, #fixtures/*

Code Standards

TypeScript strict mode. No any, no as unknown as T. ESM only. Node builtins use node: prefix. Relative imports include .js extension. Maximum 300 LOC per file.

Documentation: Microsoft TSDoc (not JSDoc). Every public function must have TSDoc with an @example tag.

Errors: All errors extend PramanError with code, attempted, retryable, suggestions[]. Use pino logger — never console.log.

Linting: 11 ESLint plugins, zero tolerance (0 errors, 0 warnings).

Commit Messages

We use Conventional Commits enforced by commitlint.

feat(proxy): add bidirectional type conversion
fix(bridge): handle stale control reference
docs(auth): add Office365 strategy example
test(core): add config validation edge cases

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Limits: Subject max 72 characters, header max 100 characters.

Testing

Unit: Vitest 4.x with describe / it pattern. File naming: *.test.ts. Hermetic — no network calls.

Integration: Playwright with test.step(). File naming: *.spec.ts. Requires SAP credentials.

Coverage: Tier 1 (errors): 100%. Tier 2 (core): 95%. Tier 3 (global): 90%. Per-file enforcement.

Git Hooks

HookAction
pre-commitlint-staged (ESLint + Prettier on staged files)
commit-msgcommitlint validation
pre-pushtypecheck + unit tests with coverage + build

Pull Requests

  1. Create a feature branch from main
  2. Make your changes following the code standards above
  3. Ensure npm run ci passes locally
  4. Submit a PR with a clear description of what and why
  5. Wait for CI checks (3-OS matrix) and code review

Reporting Issues

  • Bugs: Open a GitHub issue with steps to reproduce
  • Security vulnerabilities: Email [email protected] (see SECURITY.md)
  • Feature requests: Open a GitHub issue with use case description

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.