diff --git a/docs/automation/pom-login-example.md b/docs/automation/pom-login-example.md new file mode 100644 index 0000000..c56117b --- /dev/null +++ b/docs/automation/pom-login-example.md @@ -0,0 +1,68 @@ +# POM: Reusable Login Module + +On this example we will create a robust, reusable login module that Wopee.io can reference without re-analysis. This guide shows you how to build, register, and use login components efficiently. + +## pages/LoginPage.ts + +```typescript +import { Page, Locator, expect } from "@playwright/test"; + +export class LoginPage { + readonly page: Page; + readonly usernameInput: Locator; + readonly passwordInput: Locator; + readonly loginButton: Locator; + readonly errorMessage: Locator; + readonly forgotPasswordLink: Locator; + + constructor(page: Page) { + this.page = page; + this.usernameInput = page.locator('[data-testid="username-input"]'); + this.passwordInput = page.locator('[data-testid="password-input"]'); + this.loginButton = page.locator('[data-testid="login-button"]'); + this.errorMessage = page.locator('[data-testid="error-message"]'); + this.forgotPasswordLink = page.locator('[data-testid="forgot-password"]'); + } + + async goto() { + await this.page.goto("/login"); + await this.page.waitForLoadState("networkidle"); + } + + async login(username: string, password: string) { + await this.usernameInput.fill(username); + await this.passwordInput.fill(password); + await this.loginButton.click(); + + // Wait for navigation or success indicator + await this.page.waitForURL("**/dashboard", { timeout: 10000 }); + } + + async loginWithInvalidCredentials(username: string, password: string) { + await this.usernameInput.fill(username); + await this.passwordInput.fill(password); + await this.loginButton.click(); + + // Wait for error message + await this.errorMessage.waitFor({ state: "visible" }); + } + + async getErrorMessage() { + return await this.errorMessage.textContent(); + } + + async isLoggedIn() { + // Check for dashboard URL or authenticated user indicator + return ( + this.page.url().includes("/dashboard") || + (await this.page.locator('[data-testid="user-menu"]').isVisible()) + ); + } + + async logout() { + await this.page.locator('[data-testid="user-menu"]').click(); + await this.page.locator('[data-testid="logout-button"]').click(); + await this.page.waitForURL("**/login"); + } +} +``` \ No newline at end of file diff --git a/docs/concepts/analysis-inputs.md b/docs/concepts/analysis-inputs.md new file mode 100644 index 0000000..5837b30 --- /dev/null +++ b/docs/concepts/analysis-inputs.md @@ -0,0 +1,115 @@ +# Analysis - Inputs + +First go to strategy for test analysis is to use our AI Testing Agent to analyze the application and generate test cases. Apart from crawling, you can also use Jira stories, Figma designs, or any other artifact to generate test cases. Actually, this is a more efficient way to generate test cases, because the AI Testing Agent can use only information from your crawling instruction / prompt and context from collected screenshots and HTML. + +## Input Types which will improve quality of your test analysis + +### 1. Jira Stories + +- **User Stories** - Business requirements and acceptance criteria +- **Bug Reports** - Defect descriptions and reproduction steps +- **Feature Requests** - New functionality specifications +- **Epics** - High-level feature groupings + +### 2. Figma Designs + +- **UI Mockups** - Visual design specifications +- **Prototypes** - Interactive design flows +- **Design Systems** - Component libraries and patterns +- **Wireframes** - Low-fidelity layout concepts + +### 3. Draft Test Cases + +- **Manual Test Scripts** - Existing test documentation +- **Test Plans** - Testing strategy documents +- **Bug Reports** - Known issues and edge cases +- **Requirements Documents** - Business specifications + +## Examples + +### Jira Story Example + +**Example Jira Story**: + +``` +Title: User can send secure messages +Description: As a user, I want to send secure messages to other users so that I can communicate privately. + +Acceptance Criteria: +- User can compose a new message +- User can select recipients from contact list +- User can attach files up to 10MB +- User can mark message as urgent +- User receives confirmation when message is sent +- User can view sent message in outbox + +Technical Notes: +- Messages are encrypted end-to-end +- File upload supports: PDF, DOC, JPG, PNG +- Maximum 5 recipients per message +``` + +Step 1: Add an user story: + +![Add an user story](../../img/concepts/analysis-inputs/add-user-story.png) + +Step 2: Prompt for user story: + +![Prompt for user story](../../img/concepts/analysis-inputs/prompt-user-story.png) + +Step 3: Test case generated: + +![Test case generated](../../img/concepts/analysis-inputs/tests-generated.png) + +### Figma Frame Example + +**Upload Requirements**: + +- **Format**: Export your Figma frame as PNG, JPG +- **Context**: Include relevant UI states (empty, filled, error) +- **Instructions**: Add all important information for complex interactions into instructions. + +### Draft Test Case Example + +**Example Test Case Example**: + +``` +Test Case: TC-001 - User can compose a new message +Preconditions: User is logged in +Steps: +1. Navigate to Messages page +2. Click "Compose" button +3. Fill recipient field with "recipient@example.com" +4. Enter subject line +5. Type message body +6. Click "Send" button +7. Verify message is sent successfully +Expected Result: Message is sent successfully and is visible in outbox +``` + +## Artifact Mapping Table + +| Artifact Type | What Wopee Extracts | Affects User Stories | Affects Tests | +| -------------------- | --------------------------------------------------------- | --------------------------- | ------------------------------ | +| **Jira Story** | Title, description, acceptance criteria, labels, priority | ✅ Creates/updates stories | ✅ Generates test scenarios | +| **Figma Design** | UI elements, interactions, states, design tokens | ✅ Adds visual context | ✅ Creates visual tests | +| **Draft Test Case** | Steps, expected results, preconditions | ✅ Validates requirements | ✅ Generates test code | +| **Bug Report** | Issue description, steps to reproduce | ✅ Creates regression tests | ✅ Generates negative tests | +| **Requirements Doc** | Business rules, constraints, workflows | ✅ Creates user stories | ✅ Generates integration tests | + +## Best Practices + +### ✅ Do + +- **Provide context** - Add descriptions to all artifacts +- **Use consistent naming** - Standardize artifact IDs +- **Include multiple states** - Upload different UI states +- **Validate extracted data** - Review what Wopee.io extracts +- **Update artifacts** - Keep inputs current with application changes + +### ❌ Don't + +- **Upload outdated designs** - Ensure artifacts match current state +- **Skip validation** - Always review generated output +- **Ignore conflicts** - Resolve contradictions between sources +- **Forget versioning** - Track changes to artifacts over time diff --git a/docs/analysis.md b/docs/concepts/analysis-process.md similarity index 98% rename from docs/analysis.md rename to docs/concepts/analysis-process.md index 29900c7..41baf67 100644 --- a/docs/analysis.md +++ b/docs/concepts/analysis-process.md @@ -6,7 +6,7 @@ Below is a step-by-step overview of how your application is analyzed and how you ## New Analysis -![](img/analysis/2025-04-16_04-39.png) +![New analysis](../../img/analysis/2025-04-16_04-39.png) Before starting the analysis, you can tailor how source data is collected and provide specific instructions for the crawler: @@ -25,7 +25,6 @@ Before starting the analysis, you can tailor how source data is collected and pr Once you’ve configured these options, you can start the analysis or cancel to return to the previous screen. - ## 1. Collecting Input Data **What Happens:** @@ -99,4 +98,4 @@ Well-structured tests lead to dependable and actionable results. - ▶️ **Run Tests:** Execute tests immediately to validate functionality. - 💾 **Save to Git:** Store finalized scenarios and code in your connected Git repository. - ➕ **Add New:** Create additional user stories or test cases as needed. -- 🔄 **Regenerate:** Refresh scenarios or code based on new instructions. \ No newline at end of file +- 🔄 **Regenerate:** Refresh scenarios or code based on new instructions. diff --git a/docs/concepts/prompting-guidelines.md b/docs/concepts/prompting-guidelines.md new file mode 100644 index 0000000..3bdb63d --- /dev/null +++ b/docs/concepts/prompting-guidelines.md @@ -0,0 +1,293 @@ +# Prompting Guidelines - Good Practices + +Master the art of writing effective prompts for Wopee.io to generate high-quality tests and documentation. + +## Core Prompt Structure + +### Basic Template + +```markdown +Goal: [What you want to achieve] +Scope: [What to include/exclude] +Assumptions: [What can be assumed] +Constraints: [What to avoid or limit] +Output: [Expected deliverables] +``` + +### Advanced Template + +```markdown +Goal: [Specific objective] +Context: [Background information] +Scope: [Boundaries and limitations] +Assumptions: [Pre-conditions and known state] +Constraints: [Restrictions and exclusions] +Requirements: [Specific needs] +Output: [Expected format and content] +Examples: [Sample outputs if helpful] +``` + +## High-Signal Prompt Patterns + +### Pattern 1: Use browser local storage to store state of the application + +```markdown +Goal: Test "Secure Messages" functionality only. +Assumptions: Browser local storage is uploaded and user is authenticated (do not re-login). +Constraints: Do not re-login; focus solely on Secure Messages flows: compose, send, receive, read/unread, attachments. +``` + +**When to Use**: You have stable modules and want to focus on new features. + +### Pattern 2: Apply Page Object Model Structure + +```markdown +Goal: Generate tests for "E-commerce Checkout" flow +Context: Swag Labs e-commerce application with login, products, cart, and checkout pages + +POM Structure Required: + +- BasePage: Common functionality and Wopee integration +- LoginPage: Authentication with methods like login(username, password) +- ProductsPage: Product browsing with methods like addToCart(productName) +- CartPage: Cart management with methods like proceedToCheckout() +- CheckoutPage: Checkout process with methods like fillCheckoutInfo(firstName, lastName, postalCode) +- NavigationPage: Menu and social links handling +``` + +**When to Use**: You need a complete POM implementation for a multi-page application flow. Wopee.io generates test scenarios and user stories, while you implement the POM structure to ensure optimal maintainability and reusability. This approach gives you full control over your test architecture and allows you to establish consistent patterns across your test suite. Once implemented, these POMs become reusable components that can be referenced in future prompts for generating tests for new features. + +### Pattern 3: Constrain Analysis Scope + +```markdown +Goal: Test "User Profile" section +Scope: /profile/\* pages only +Assumptions: User is authenticated and can access profile +**Exclude:** Login, navigation, other sections +Focus: Profile editing, avatar upload, preferences +Output: Focused test suite for profile functionality +``` + +**When to Use**: You want to limit analysis to specific application sections. + +### Pattern 4: Generate from Jira and Figma (typically on the 4th step of analysis process) + +```markdown +Goal: Generate tests for following user story: + +- Title: User can send secure messages +- Description: As a user, I want to send secure messages to other users so that I can communicate privately. + +Acceptance Criteria: + +- User can compose a new message +- User can select recipients from contact list +- User can attach files up to 10MB +- User can mark message as urgent +- User receives confirmation when message is sent +- User can view sent message in outbox + +Technical Notes: + +- Messages are encrypted end-to-end +- File upload supports: PDF, DOC, JPG, PNG +- Maximum 5 recipients per message + +Assumptions: User is authenticated, UI matches Figma design + +Constraints: prefer `data-testid` selectors and use visual click when possible. +``` + +**When to Use**: You have requirements and designs to incorporate. + +### Pattern 5: Focus on Specific Flows + +```markdown +Goal: Test "File Upload" feature in messages +Scope: File upload functionality within /messages/compose +Assumptions: User can access message composition +Exclude: Message sending, recipient selection, other features +``` + +**When to Use**: You want to test specific functionality in detail. + +### Pattern 6: Error Handling Focus + +```markdown +Goal: Test error scenarios in "User Profile" section +Scope: /profile/\* pages with error conditions +Assumptions: User is authenticated and can access profile +Focus: Validation errors, network failures, permission denied +Exclude: Happy path scenarios (already covered) +Output: Negative test cases and error handling tests +``` + +**When to Use**: You want to test error conditions and edge cases. + +## Do's and Don'ts + +### ✅ Do + +| Practice | Example | Why It Works | +| ------------------------- | -------------------------------------------- | --------------------------------------- | +| **Be specific** | "Test Secure Messages compose functionality" | Clear scope prevents scope creep | +| **Reference modules** | "Use existing Login module" | Avoids re-analysis of stable components | +| **Set boundaries** | "Focus on /profile/\* pages only" | Limits analysis to target areas | +| **State assumptions** | "User is authenticated" | Provides context for test generation | +| **Specify output format** | "Generate POM-compatible Playwright tests" | Ensures desired code structure | +| **Include constraints** | "Do not test login flow" | Prevents unwanted analysis | +| **Use examples** | "Like the LoginPage.ts pattern" | Provides clear reference | + +### ❌ Don't + +| Practice | Example | Why It Fails | +| ------------------------------ | ------------------------------------------ | ------------------------------------------ | +| **Be vague** | "Test the application" | Too broad, unclear scope | +| **Ignore existing work** | "Analyze everything" | Wastes time re-analyzing stable components | +| **Skip context** | "Generate tests" | Missing assumptions leads to poor results | +| **Forget constraints** | "Test all features" | May include unwanted functionality | +| **Unclear output** | "Create some tests" | Unclear format and expectations | +| **Contradictory instructions** | "Test login but don't test authentication" | Confusing requirements | + +## Scenario-Specific Templates + +### Template 1: E-commerce POM Implementation + +Could be used as a initial prompt for new analysis process or to generate tests for specific user story. + +```markdown +Goal: Implement complete Page Object Model for "Swag Labs" e-commerce application +Context: Multi-page e-commerce flow with login, products, cart, and checkout + +POM Structure Required: + +- BasePage: Common functionality, Wopee integration, navigation helpers +- LoginPage: Authentication with business-focused methods +- ProductsPage: Product browsing and cart operations +- CartPage: Cart management and checkout initiation +- CheckoutPage: Checkout process and form handling +- NavigationPage: Menu and social link interactions + +Page Object Requirements: + +- Extend BasePage for common functionality +- Business-focused method names (e.g., "addBackpackToCart()") +- Private selectors with data-testid attributes +- Visual assertions and Wopee tracking +- Single responsibility principle +- Comprehensive error handling + +Example Method Signatures: + +- LoginPage: login(username, password), verifyLoginFormFields() +- ProductsPage: addBackpackToCart(), verifyProductsGrid(), goToCart() +- CartPage: proceedToCheckout(), removeBackpackFromCart() +- CheckoutPage: fillCheckoutInfo(firstName, lastName, postalCode), finishOrder() +- NavigationPage: openHamburgerMenu(), clickTwitterLink() +``` + +### Template 2: New Feature Testing + +Could be used as a initial prompt for new analysis process or to generate tests for specific user story. + +```markdown +Goal: Test new "Advanced Search" feature +Context: Search functionality with filters, sorting, and pagination +Scope: /search/\* pages and search-related components + +Assumptions: + +- User is authenticated +- Search index is populated with test data +- Basic search functionality exists + +Constraints: + +- Do not test basic search (already covered) +- Focus on advanced features only +- Do not modify existing search tests + +Requirements: + +- Test filter combinations +- Test sorting options +- Test pagination +- Test search result accuracy +``` + +## When to Apply POM Patterns + +### POM Application Guidelines + +| Scenario | Apply POM | Reason | +| ----------------------------- | --------- | --------------------------------------- | +| **Multi-page applications** | ✅ Yes | Complex navigation and state management | +| **E-commerce flows** | ✅ Yes | Multiple pages with business logic | +| **Single page components** | ❌ No | Overkill for simple components | +| **API testing only** | ❌ No | No UI interactions needed | +| **Visual regression testing** | ✅ Yes | Page-level visual assertions | +| **End-to-end workflows** | ✅ Yes | Complex user journeys | + +### POM Structure Indicators + +**Apply POM when you have:** + +- Multiple pages with distinct functionality +- Complex user workflows spanning multiple pages +- Business logic that needs to be encapsulated +- Visual testing requirements +- Need for reusable page interactions +- Team collaboration on test maintenance + +**Skip POM when you have:** + +- Single page applications with simple interactions +- API-only testing requirements +- Quick exploratory testing +- Simple component testing + +## Prompt Optimization Tips + +| Tip | Poor Example | Better Example | Why It Works | +| --------------------------- | -------------------- | ------------------------------------------------------------------------ | --------------------------------------- | +| **Start with Clear Goals** | "Test the app" | "Test user registration flow with validation scenarios" | Specific objectives prevent scope creep | +| **Provide Context** | "Generate tests" | "Generate tests for a e-commerce application with user authentication" | Application context improves relevance | +| **Set Clear Boundaries** | "Test everything" | "Test only the checkout process, exclude product browsing" | Defined scope focuses analysis | +| **Reference Existing Work** | "Create login tests" | "Use existing LoginPage.ts module, focus on new authentication features" | Avoids re-analyzing stable components | +| **Specify Output Format** | "Create some tests" | "Generate POM-compatible Playwright tests with TypeScript" | Ensures desired code structure | + +## Common Mistakes to Avoid + +| Mistake | Problem Example | Solution | Why It Matters | +| ----------------------------- | -------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------ | +| **Overly Broad Scope** | "Test the entire application" | Break down into specific features or modules | Prevents analysis paralysis and unclear results | +| **Ignoring Existing Modules** | "Generate all tests from scratch" | Reference existing stable modules | Saves time and maintains consistency | +| **Unclear Requirements** | "Test the search feature" | Specify what aspects of search to test | Ensures relevant and focused test generation | +| **Missing Context** | "Create tests for the form" | Provide application context and user scenarios | Improves test relevance and coverage | +| **Unrealistic Expectations** | "Generate perfect tests in one prompt" | Use iterative approach with multiple focused prompts | Achieves better results through incremental refinement | + +## Prompt Validation Checklist + +Before sending a prompt, verify: + +- [ ] **Goal is specific and clear** +- [ ] **Scope is well-defined** +- [ ] **Assumptions are stated** +- [ ] **Constraints are specified** +- [ ] **Output format is clear** +- [ ] **Context is provided** +- [ ] **Existing work is referenced** +- [ ] **Requirements are realistic** + +### POM-Specific Validation + +When applying POM patterns, also verify: + +- [ ] **Page objects are clearly defined** with distinct responsibilities +- [ ] **Business-focused method names** are specified (not technical actions) +- [ ] **BasePage inheritance** is mentioned for common functionality +- [ ] **Visual testing integration** is included if needed +- [ ] **Selector strategy** is specified (data-testid preferred) +- [ ] **Error handling** requirements are outlined +- [ ] **Example usage** demonstrates page object interaction +- [ ] **Single responsibility** principle is maintained diff --git a/docs/img/concepts/analysis-inputs/add-user-story.png b/docs/img/concepts/analysis-inputs/add-user-story.png new file mode 100644 index 0000000..a4d81d5 Binary files /dev/null and b/docs/img/concepts/analysis-inputs/add-user-story.png differ diff --git a/docs/img/concepts/analysis-inputs/prompt-user-story.png b/docs/img/concepts/analysis-inputs/prompt-user-story.png new file mode 100644 index 0000000..443f219 Binary files /dev/null and b/docs/img/concepts/analysis-inputs/prompt-user-story.png differ diff --git a/docs/img/concepts/analysis-inputs/tests-generated.png b/docs/img/concepts/analysis-inputs/tests-generated.png new file mode 100644 index 0000000..c29c3cd Binary files /dev/null and b/docs/img/concepts/analysis-inputs/tests-generated.png differ diff --git a/docs/security/enterprise-connectivity.md b/docs/security/enterprise-connectivity.md new file mode 100644 index 0000000..083e908 --- /dev/null +++ b/docs/security/enterprise-connectivity.md @@ -0,0 +1,73 @@ +# Enterprise Connectivity + +Connect Wopee.io to applications behind VPN, firewalls, or in secure enterprise environments. + +## Connectivity Options + +### Option 1: IP Allowlisting (Recommended) + +Allow Wopee.io cloud IPs to access your internal systems. + +#### Wopee.io IP Ranges + +**Production IPs** (to be provided by Wopee.io): + +``` +# Primary Wopee.io Cloud IPs +203.0.113.0/24 # Wopee.io Cloud - Primary +198.51.100.0/24 # Wopee.io Cloud - Secondary +192.0.2.0/24 # Wopee.io Cloud - Backup + +# Regional IPs (if applicable) +# North America: 203.0.113.0/24 +# Europe: 198.51.100.0/24 +# Asia Pacific: 192.0.2.0/24 +``` + +!!! caution "IP Addresses" + + The IP ranges above are placeholders. Contact Wopee.io support for actual IP addresses for your region. + +### Option 2: Secure Tunnel (Enterprise Plan) + +Establish a secure tunnel between Wopee.io and your internal network. + +#### Architecture + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Wopee.io │ │ Secure │ │ Your Internal │ +│ Cloud │◄──►│ Tunnel │◄──►│ Network │ +│ │ │ (VPN/SSH) │ │ │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ +``` + +### Option 3: Self-Hosted Runner + +Run Wopee.io agents within your internal network. + +#### Architecture + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Wopee.io │ │ Your Internal │ │ Your Internal │ +│ Cloud │◄──►│ Runner │◄──►│ Applications │ +│ (Control) │ │ (Agent) │ │ (SUT) │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ +``` + +## Choose Connectivity Method + +| Factor | IP Allowlisting | Secure Tunnel | Self-Hosted Runner | +| -------------------- | --------------- | ------------- | ------------------ | +| **Setup Complexity** | Low | Medium | High | +| **Security** | Medium | High | Highest | +| **Maintenance** | Low | Medium | High | +| **Cost** | Free | Enterprise | Enterprise | +| **Control** | Low | Medium | High | + +## Related Pages + +- [Quick Start Guide](/docs/get-started/quickstart.md) - Initial setup +- [Stability Guide](/docs/troubleshooting/stability.md) - Troubleshooting +- [Billing and Licensing](/docs/billing-and-licensing.md) - Enterprise plans diff --git a/mkdocs.yml b/mkdocs.yml index 6f286ca..70b8b7e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,9 +1,11 @@ site_name: Wopee.io nav: - 🚀 Autonomous Testing: index.md - - 🤖 Getting started: bot.md - - ✨ Analysis Process: analysis.md - - 🧑‍✈️ Pilot projects: pilot-projects.md + - Concepts: + - ✨ Analysis - Process: concepts/analysis-process.md + - 🔗 Analysis - Inputs: concepts/analysis-inputs.md + - 📖 Prompting Guidelines: concepts/prompting-guidelines.md + - 📃 POM example - Login: automation/pom-login-example.md - Visual Testing with...: - ≫ Cypress: - Getting started: cypress/01-getting-started.md @@ -22,6 +24,8 @@ nav: - 🗄️ Browser local storage: browser-local-storage.md - 🌐 Project context: project-context.md - Other docs: + - 🧑‍✈️ Pilot projects: pilot-projects.md + - 🔒 Enterprise Connectivity: security/enterprise-connectivity.md - 📖 Glossary: glossary.md theme: