samaro-uitest 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Samaro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,336 @@
+# SamaroUItest
+
+<p align="center">
+  <strong>Comprehensive Testing Framework for Angular</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/samaro-uitest">
+    <img src="https://img.shields.io/npm/v/samaro-uitest.svg" alt="npm version">
+  </a>
+  <a href="https://github.com/samaro/samaro-uitest/blob/main/LICENSE">
+    <img src="https://img.shields.io/npm/l/samaro-uitest.svg" alt="license">
+  </a>
+  <a href="https://angular.io">
+    <img src="https://img.shields.io/badge/Angular-15%2B-red.svg" alt="Angular 15+">
+  </a>
+</p>
+
+<p align="center">
+  🚀 <strong>Vitest</strong> + 🎭 <strong>Playwright</strong> + 📊 <strong>Allure</strong>
+</p>
+
+---
+
+## Features
+
+- ✅ **One-Command Setup** - Get started in minutes with `ng add samaro-uitest`
+- ⚡ **Lightning Fast** - Vitest for rapid unit testing feedback
+- 🎭 **Real Browser Testing** - Playwright for E2E and component tests
+- 📊 **Beautiful Reports** - Allure integration for all test types
+- 🔧 **Pre-Configured** - Works out of the box with Angular
+- 🛠️ **Helper Library** - Common testing utilities included
+- 🔍 **Debug Interface** - Access Angular app state in tests
+- 🚀 **CI/CD Ready** - GitHub Actions, GitLab CI, Azure DevOps support
+
+---
+
+## Installation
+
+### Using Angular CLI (Recommended)
+
+```bash
+ng add samaro-uitest
+```
+
+### Using npm
+
+```bash
+npm install --save-dev samaro-uitest
+npx samaro-init
+```
+
+### Install Playwright Browsers
+
+```bash
+npx playwright install chromium
+```
+
+---
+
+## Quick Start
+
+After installation, you can immediately start testing:
+
+```bash
+# Run unit tests
+npm run test
+
+# Run E2E tests
+npm run test:e2e
+
+# Run component tests
+npm run test:ct
+
+# Generate and view reports
+npm run allure:generate
+npm run allure:open
+```
+
+---
+
+## Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run test` | Run unit tests with Vitest |
+| `npm run test:run` | Run unit tests once (CI mode) |
+| `npm run test:ui` | Run unit tests with UI |
+| `npm run test:coverage` | Run unit tests with coverage |
+| `npm run test:e2e` | Run E2E tests with Playwright |
+| `npm run test:e2e:ui` | Run E2E tests with Playwright UI |
+| `npm run test:e2e:headed` | Run E2E tests in headed mode |
+| `npm run test:ct` | Run component tests |
+| `npm run allure:generate` | Generate Allure reports |
+| `npm run allure:open` | Open Allure reports |
+| `npm run allure:clean` | Clean Allure results |
+
+---
+
+## Writing Tests
+
+### Unit Tests
+
+```typescript
+// src/app/services/user.service.spec.ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import { TestBed } from '@angular/core/testing';
+import { UserService } from './user.service';
+
+describe('UserService', () => {
+  let service: UserService;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({});
+    service = TestBed.inject(UserService);
+  });
+
+  it('should be created', () => {
+    expect(service).toBeTruthy();
+  });
+});
+```
+
+### E2E Tests
+
+```typescript
+// e2e/auth.spec.ts
+import { test, expect } from '@playwright/test';
+import { generateUniqueUser, register } from 'samaro-uitest/helpers';
+
+test('user can register', async ({ page }) => {
+  const user = generateUniqueUser();
+  
+  await register(page, user.username, user.email, user.password);
+  
+  await expect(page).toHaveURL('/');
+});
+```
+
+### Component Tests
+
+```typescript
+// ct-tests/button.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('button renders correctly', async ({ page }) => {
+  await page.goto('/button-test');
+  
+  const button = page.locator('app-button');
+  await expect(button).toBeVisible();
+});
+```
+
+---
+
+## Test Helpers
+
+### Debug Interface
+
+Access your Angular app's state during tests:
+
+```typescript
+import { getToken, getAuthState, waitForAuthState } from 'samaro-uitest/helpers';
+
+test('user login', async ({ page }) => {
+  await login(page, 'user@example.com', 'password');
+  
+  // Wait for auth state
+  await waitForAuthState(page, 'authenticated');
+  
+  // Get token
+  const token = await getToken(page);
+  expect(token).toBeTruthy();
+});
+```
+
+### Authentication
+
+```typescript
+import { generateUniqueUser, register, login, logout } from 'samaro-uitest/helpers';
+
+const user = generateUniqueUser();
+await register(page, user.username, user.email, user.password);
+await logout(page);
+await login(page, user.email, user.password);
+```
+
+### API Helpers
+
+Speed up tests by using APIs for setup:
+
+```typescript
+import { registerUserViaAPI } from 'samaro-uitest/helpers';
+
+test('create article', async ({ page, request }) => {
+  const { token } = await registerUserViaAPI(request, {
+    username: 'testuser',
+    email: 'test@example.com',
+    password: 'password123',
+  });
+  
+  // Use token for authenticated requests
+});
+```
+
+---
+
+## Configuration
+
+### Vitest Configuration
+
+```typescript
+// vitest.config.ts
+import { createVitestConfig, mergeConfig } from 'samaro-uitest/config';
+
+export default mergeConfig(
+  createVitestConfig({
+    testGlob: 'src/**/*.spec.ts',
+  }),
+  {
+    test: {
+      coverage: {
+        exclude: ['**/legacy/**'],
+      },
+    },
+  }
+);
+```
+
+### Playwright Configuration
+
+```typescript
+// playwright.config.ts
+import { createPlaywrightConfig } from 'samaro-uitest/config';
+
+export default createPlaywrightConfig({
+  baseURL: 'http://localhost:4200',
+  testDir: './e2e',
+  webServerCommand: 'npm run start',
+  webServerPort: 4200,
+});
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `API_MODE` | Use API for setup operations | `true` |
+| `API_BASE` | Base URL for API calls | `http://localhost:4200/api` |
+| `DEBUG_INTERFACE_NAME` | Name of debug interface | `__app_debug__` |
+| `CI` | CI mode (auto-clean results) | `false` |
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npx playwright install chromium
+      - run: npm run test:run
+      - run: npm run test:e2e
+      - run: npm run allure:generate
+```
+
+---
+
+## Troubleshooting
+
+### Playwright browsers not installed
+
+```bash
+npx playwright install chromium
+```
+
+### Tests fail with timeout
+
+Increase timeout in configuration:
+
+```typescript
+export default createPlaywrightConfig({
+  webServer: {
+    timeout: 180_000,
+  },
+});
+```
+
+### Debug interface not available
+
+Implement debug interface in your Angular app:
+
+```typescript
+// app.component.ts
+if (typeof window !== 'undefined') {
+  window.__app_debug__ = {
+    getToken: () => this.authService.getToken(),
+    getAuthState: () => this.authService.getAuthState(),
+    getCurrentUser: () => this.authService.getCurrentUser(),
+  };
+}
+```
+
+---
+
+## Documentation
+
+- [Vitest Documentation](https://vitest.dev/)
+- [Playwright Documentation](https://playwright.dev/)
+- [Allure Documentation](https://docs.qameta.io/allure/)
+- [Angular Testing Guide](https://angular.io/guide/testing)
+
+---
+
+## License
+
+MIT © [Samaro](https://github.com/samaro)
+
+---
+
+<p align="center">
+  Made with ❤️ for the Angular community
+</p>

package/bin/samaro-allure.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+};
+
+const ALLURE_DIRS = [
+  { name: 'Unit Tests', dir: 'allure-unit-results', type: 'unit' },
+  { name: 'E2E Tests', dir: 'allure-e2e-results', type: 'e2e' },
+  { name: 'Component Tests', dir: 'allure-ct-results', type: 'ct' },
+];
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function generateReports() {
+  log('\n📊 Generating Allure reports...\n', 'bright');
+  
+  let generatedCount = 0;
+  
+  for (const { name, dir, type } of ALLURE_DIRS) {
+    const resultsPath = path.join(process.cwd(), dir);
+    const reportPath = path.join(process.cwd(), 'allure-reports', type);
+    
+    if (fs.existsSync(resultsPath)) {
+      try {
+        execSync(`npx allure generate "${resultsPath}" --output "${reportPath}" --clean`, {
+          stdio: 'pipe',
+        });
+        log(`  ✓ Generated ${name} report`, 'green');
+        generatedCount++;
+      } catch (error) {
+        log(`  ✗ Failed to generate ${name} report`, 'red');
+      }
+    } else {
+      log(`  ⚠ No results found for ${name}`, 'yellow');
+    }
+  }
+  
+  if (generatedCount > 0) {
+    log(`\n✅ Generated ${generatedCount} report(s)`, 'green');
+    log(`📂 Reports location: ${path.join(process.cwd(), 'allure-reports')}\n`, 'cyan');
+  } else {
+    log('\n⚠ No reports generated. Run tests first.\n', 'yellow');
+  }
+}
+
+function openReports() {
+  log('\n🌐 Opening Allure reports...\n', 'bright');
+  
+  const reportsPath = path.join(process.cwd(), 'allure-reports');
+  if (!fs.existsSync(reportsPath)) {
+    log('  ✗ No reports found. Run "samaro-allure generate" first.\n', 'red');
+    return;
+  }
+  
+  // Check available reports
+  const availableReports = fs.readdirSync(reportsPath).filter(name => {
+    return fs.statSync(path.join(reportsPath, name)).isDirectory();
+  });
+  
+  if (availableReports.length === 0) {
+    log('  ✗ No reports found.\n', 'red');
+    return;
+  }
+  
+  // Open unit report by default, or the first available
+  const reportToOpen = availableReports.includes('unit') ? 'unit' : availableReports[0];
+  const reportPath = path.join(reportsPath, reportToOpen);
+  
+  try {
+    log(`  Opening ${reportToOpen} report...`, 'cyan');
+    execSync(`npx allure open "${reportPath}"`, { stdio: 'inherit' });
+  } catch (error) {
+    log(`  ✗ Failed to open report: ${error.message}\n`, 'red');
+  }
+}
+
+function cleanResults() {
+  log('\n🧹 Cleaning Allure results and reports...\n', 'bright');
+  
+  let cleanedCount = 0;
+  
+  for (const { dir } of ALLURE_DIRS) {
+    const fullPath = path.join(process.cwd(), dir);
+    if (fs.existsSync(fullPath)) {
+      try {
+        fs.rmSync(fullPath, { recursive: true, force: true });
+        log(`  ✓ Removed ${dir}/`, 'green');
+        cleanedCount++;
+      } catch (error) {
+        log(`  ✗ Failed to remove ${dir}/: ${error.message}`, 'red');
+      }
+    }
+  }
+  
+  // Also clean the reports directory
+  const reportsPath = path.join(process.cwd(), 'allure-reports');
+  if (fs.existsSync(reportsPath)) {
+    try {
+      fs.rmSync(reportsPath, { recursive: true, force: true });
+      log(`  ✓ Removed allure-reports/`, 'green');
+      cleanedCount++;
+    } catch (error) {
+      log(`  ✗ Failed to remove allure-reports/: ${error.message}`, 'red');
+    }
+  }
+  
+  if (cleanedCount > 0) {
+    log('\n✅ Cleanup complete!\n', 'green');
+  } else {
+    log('\nℹ Nothing to clean\n', 'yellow');
+  }
+}
+
+function showHelp() {
+  console.log(`
+SamaroUItest Allure Manager
+
+Usage: samaro-allure [command]
+
+Commands:
+  generate    Generate Allure reports from test results
+  open        Open Allure reports in browser
+  clean       Remove all Allure results and reports
+  help        Show this help message
+
+Examples:
+  samaro-allure generate
+  samaro-allure open
+  samaro-allure clean
+`);
+}
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'generate':
+    generateReports();
+    break;
+  case 'open':
+    openReports();
+    break;
+  case 'clean':
+    cleanResults();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    showHelp();
+    break;
+  default:
+    if (!command) {
+      console.error('❌ Error: No command provided');
+      showHelp();
+      process.exit(1);
+    } else {
+      console.error(`❌ Unknown command: ${command}`);
+      showHelp();
+      process.exit(1);
+    }
+}