From 3f3067ea0c9360393ce26c06c4b24dbc8cd869a3 Mon Sep 17 00:00:00 2001 From: Deb Jagadeba Date: Mon, 18 Aug 2025 15:38:45 +1000 Subject: [PATCH 1/3] Update README.md --- README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 172770f..11a29d6 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,25 @@ > **Revolutionary Self-Healing Locator System for Playwright** > Transform fragile selectors into intelligent, self-healing locators with automatic fallback strategies. -[![npm version](https://badge.fury.io/js/locatorpro-playwright.svg)](https://badge.fury.io/js/locatorpro-playwright) +[![npm version](https://badge.fury.io/js/locatorpro-playwright.svg)](https://github.com/debasisj/locatorpro-playwright) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Tests](https://github.com/debasisj/locatorpro-playwright/actions/workflows/ci.yml/badge.svg)](https://github.com/debasisj/locatorpro-playwright/actions/workflows/ci.yml) + ## ๐Ÿš€ **Why LocatorPro?** +**Playwright already has excellent built-in locators** like `getByRole()`, `getByText()`, and `getByTestId()` that are robust and reliable. These should be your first choice for most scenarios. + +**However, you need LocatorPro when:** +- Working with **legacy applications** where you can't control the markup +- Dealing with **dynamically generated IDs** or **changing class names** +- Elements lack proper **test IDs** or **semantic roles** +- You need to find elements by **contextual relationships** (e.g., "Add to Cart" button for a specific product) +- **Migrating existing tests** with fragile selectors without rewriting everything +- Building tests for **third-party applications** where you can't modify the HTML + +LocatorPro **enhances** Playwright's locators with intelligent fallbacks and contextual awareness, making your tests resilient in scenarios where standard locators fall short. + **Traditional Playwright tests break when:** - IDs change: `#submit-btn-123` โ†’ `#submit-btn-456` โŒ - Classes are renamed: `.old-button` โ†’ `.new-button` โŒ From b29855207eacdf14613a02c3bb78f3edc80157b5 Mon Sep 17 00:00:00 2001 From: Deb Jagadeba Date: Mon, 18 Aug 2025 16:22:01 +1000 Subject: [PATCH 2/3] Create CONTRIBUTING.md --- CONTRIBUTING.md | 223 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..73120d7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,223 @@ +# Contributing to LocatorPro for Playwright + +Thank you for your interest in contributing to LocatorPro! We welcome contributions from the community and are excited to see what you'll bring to the project. + +## ๐Ÿš€ Getting Started + +### Prerequisites +- Node.js 18+ or 20+ +- npm or yarn +- Git + +### Development Setup + +1. **Fork and clone the repository** + ```bash + git clone https://github.com/YOUR_USERNAME/locatorpro-playwright.git + cd locatorpro-playwright + ``` + +2. **Install dependencies** + ```bash + npm install + ``` + +3. **Start the local test server** + ```bash + npm start + # Server runs on http://localhost:3000 + ``` + +4. **Run tests to ensure everything works** + ```bash + npm test + npm run test:headed # Run with browser UI + ``` + +5. **Build the project** + ```bash + npm run build + ``` + +## ๐Ÿงช Testing + +### Running Tests +- `npm test` - Run all Playwright tests +- `npm run test:headed` - Run tests with browser visible +- `npm run test:ui` - Interactive test runner +- `npm run build` - TypeScript compilation + +### Test Structure +- `tests/core-functionality.spec.ts` - Core SmartLocator methods +- `tests/related-text.spec.ts` - Revolutionary findByRelatedText features +- `tests/self-healing.spec.ts` - Self-healing and pattern analysis +- `test-site/` - Local test site with comprehensive scenarios + +### Writing Tests +When adding new features, please include tests that cover: +- Happy path scenarios +- Edge cases and error conditions +- Cross-browser compatibility +- Performance considerations + +## ๐Ÿ“ Code Style + +### TypeScript Guidelines +- Use strict TypeScript with proper type definitions +- Follow existing code patterns and naming conventions +- Add JSDoc comments for public methods +- Use meaningful variable and function names + +### Formatting +We use standard TypeScript formatting. The project will auto-format on build. + +## ๐ŸŽฏ Types of Contributions + +### ๐Ÿ› Bug Reports +Please use the GitHub issue template and include: +- Clear description of the issue +- Steps to reproduce +- Expected vs actual behavior +- Browser and environment details +- Minimal code example + +### โœจ Feature Requests +For new features, please: +- Check existing issues first +- Describe the use case and benefit +- Provide examples of how it would work +- Consider backward compatibility + +### ๐Ÿ”ง Code Contributions + +#### Pull Request Process +1. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Make your changes** + - Follow the existing code style + - Add/update tests as needed + - Update documentation if necessary + +3. **Test your changes** + ```bash + npm test + npm run build + ``` + +4. **Commit with clear messages** + ```bash + git commit -m "feat: add smart pattern recognition for form inputs" + # or + git commit -m "fix: handle timeout errors in generateStrategies" + ``` + +5. **Push and create PR** + ```bash + git push origin feature/your-feature-name + ``` + +#### Commit Message Format +We follow conventional commits: +- `feat:` - New feature +- `fix:` - Bug fix +- `docs:` - Documentation changes +- `test:` - Adding or updating tests +- `refactor:` - Code refactoring +- `perf:` - Performance improvements +- `chore:` - Maintenance tasks + +## ๐ŸŽฏ Priority Areas for Contribution + +### High Priority +- **New locator strategies** - Additional ways to find elements +- **Performance optimizations** - Faster strategy generation +- **Cross-browser testing** - Ensure compatibility +- **Documentation improvements** - Examples and guides + +### Medium Priority +- **Framework integrations** - Jest, Cucumber, etc. +- **Visual regression detection** - Image-based locators +- **Machine learning patterns** - Smarter pattern recognition +- **Accessibility improvements** - Better ARIA support + +### Good First Issues +- **Bug fixes** - Small, well-defined issues +- **Documentation updates** - README improvements +- **Test coverage** - Additional test scenarios +- **Code examples** - Real-world usage examples + +## ๐Ÿ“š Development Guidelines + +### Architecture Overview +``` +src/ +โ”œโ”€โ”€ index.ts # Main exports +โ”œโ”€โ”€ smart-locator.ts # Core SmartLocator class +โ”œโ”€โ”€ locator-engine.ts # Strategy generation engine +โ””โ”€โ”€ types.ts # TypeScript type definitions +``` + +### Key Components +- **SmartLocator** - Main class with public API +- **LocatorEngine** - Strategy generation and DOM analysis +- **Strategy System** - Prioritized fallback mechanisms +- **Pattern Analysis** - Broken selector intelligence + +### Adding New Features +1. **Update types** in `src/types.ts` +2. **Implement logic** in appropriate files +3. **Add public methods** to `SmartLocator` class +4. **Write comprehensive tests** +5. **Update documentation** + +## ๐Ÿค Community Guidelines + +### Code of Conduct +- Be respectful and inclusive +- Provide constructive feedback +- Help newcomers get started +- Maintain professional communication + +### Getting Help +- **GitHub Discussions** - General questions and ideas +- **GitHub Issues** - Bug reports and feature requests +- **Discord/Slack** - Real-time community chat (if available) + +## ๐Ÿ“‹ Review Process + +### What We Look For +- **Code quality** - Clean, readable, maintainable code +- **Test coverage** - Comprehensive test scenarios +- **Documentation** - Clear explanations and examples +- **Backward compatibility** - Don't break existing functionality +- **Performance** - Consider impact on execution speed + +### Review Timeline +- Initial response: 2-3 business days +- Code review: 3-5 business days +- Final approval: 1-2 business days + +## ๐ŸŽ‰ Recognition + +Contributors will be: +- Added to the contributors list +- Mentioned in release notes +- Invited to become maintainers (for significant contributions) + +## ๐Ÿ“ž Questions? + +Feel free to reach out: +- **GitHub Issues** - For bug reports and feature requests +- **GitHub Discussions** - For general questions +- **Email** - [maintainer email if available] + +--- + +Thank you for contributing to LocatorPro! Together, we're making Playwright automation more reliable and accessible for everyone. ๐Ÿš€ + +## ๐Ÿ“„ License + +By contributing to LocatorPro, you agree that your contributions will be licensed under the MIT License. From e72a32759ff9c064ce19df38bc494e60cc418195 Mon Sep 17 00:00:00 2001 From: Deb Jagadeba Date: Mon, 18 Aug 2025 16:22:03 +1000 Subject: [PATCH 3/3] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 11a29d6..a340c87 100644 --- a/README.md +++ b/README.md @@ -427,7 +427,7 @@ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guid ### **Development Setup** ```bash -git clone https://github.com/your-org/locatorpro-playwright.git +git clone https://github.com/debasisj/locatorpro-playwright.git cd locatorpro-playwright npm install npm run test