@zest-pw/test 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Zest Playwright Team
+
+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,415 @@
+# Zest Playwright Test Framework
+
+Advanced Playwright test framework with automatic screenshots, custom reporting, and Zephyr Scale integration.
+
+## ✨ Features
+
+- 📸 **Automatic Screenshots** - Capture screenshots after each test step
+- 📊 **Custom JSON Reports** - Detailed test results with step information
+- 🔄 **Zephyr Scale Integration** - Automatically update test results in Zephyr
+- ⚙️ **Type-Safe Configuration** - Configure behavior via `zest.config.ts`
+- 🎯 **Step-by-Step Tracking** - Detailed information about each test step
+- 🖼️ **Base64 Screenshots in Reports** - Screenshots embedded directly in JSON
+
+## 🚀 Quick Start
+
+### 1. Install the Package
+
+```bash
+npm install --save-dev @zest-pw/test
+```
+
+### 2. Configuration
+
+The configuration file `zest.config.ts` will be automatically created in your project root after installation. If it wasn't created automatically, run:
+
+```bash
+npx zest-pw-init
+```
+
+The default configuration:
+
+```typescript
+import { defineZestConfig } from '@zest-pw/test';
+
+export default defineZestConfig({
+  reporter: {
+    saveJsonReport: true,
+    printToConsole: true,
+    outputDir: 'test-results',
+  },
+  screenshots: {
+    enabled: true,
+    includeInReport: true,
+    onlyOnFailure: false,
+  },
+  zephyr: {
+    enabled: false,
+    updateResults: false,
+  },
+});
+```
+
+### 3. Configure Playwright
+
+Update your `playwright.config.ts`:
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [
+    ['list'],
+    ['@zest-pw/test/reporter'], // Add Zest reporter
+  ],
+  // ... other Playwright config
+});
+```
+
+### 4. Write Your First Test
+
+```typescript
+import { test, expect } from '@zest-pw/test';
+
+test('TC-001: Check the title', async ({ page }) => {
+  
+  await test.step('Go to the playwright website', async () => {
+    await page.goto('https://playwright.dev/');
+  });
+
+  await test.step('Check the title', async () => {
+    await expect(page).toHaveTitle(/Playwright/);
+  });
+});
+```
+
+### 5. Run Tests
+
+```bash
+npx playwright test
+```
+
+## ⚙️ Configuration
+
+### Configuration File
+
+The `zest.config.ts` file is automatically created when you install the package. You can customize it as needed:
+
+```typescript
+import { defineZestConfig } from '@zest-pw/test';
+
+export default defineZestConfig({
+  reporter: {
+    // Save test results to JSON file
+    saveJsonReport: true,
+    
+    // Output directory for reports
+    outputDir: 'test-results',
+    
+    // Print test results to console
+    printToConsole: false,
+  },
+
+  screenshots: {
+    // Enable screenshot capture
+    enabled: true,
+    
+    // Include screenshots in JSON report
+    includeInReport: true,
+    
+    // Capture screenshots only on failure
+    onlyOnFailure: false,
+  },
+
+  zephyr: {
+    // Enable Zephyr Scale integration
+    enabled: false,
+    
+    // Update test results in Zephyr after test run
+    updateResults: false,
+  },
+});
+```
+
+For detailed configuration options, see [CONFIG.md](./CONFIG.md).
+
+## 📸 Screenshots
+
+Screenshots are automatically captured after each `test.step()` and:
+- **Embedded in JSON report** as base64 (if `includeInReport: true`)
+- **Named descriptively** based on step title and index
+- **Include error screenshots** when tests fail
+
+### Screenshot Settings
+
+```typescript
+screenshots: {
+  enabled: true,           // Enable/disable screenshots
+  includeInReport: true,   // Include in JSON report
+  onlyOnFailure: false,    // Capture only on test failure
+}
+```
+
+### Example Screenshot Output
+
+```json
+{
+  "fileName": "step_1_go_to_the_playwright_website.png",
+  "image": "image/png",
+  "body": "base64_encoded_screenshot..."
+}
+```
+
+## 📊 Test Reports
+
+### JSON Report
+
+Test results are automatically saved to `test-results/test-results.json`:
+
+```json
+{
+  "tests": [
+    {
+      "testTitle": "Check the title",
+      "testCaseKey": "TC-001",
+      "steps": [
+        {
+          "stepTitle": "Go to the playwright website",
+          "actualResult": [...],
+          "statusName": "passed"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Console Output
+
+Enable console output in your config:
+
+```typescript
+reporter: {
+  printToConsole: true,
+}
+```
+
+## 🔄 Zephyr Scale Integration
+
+### Setup
+
+1. Add environment variables:
+
+```bash
+# .env
+ZEPHYR_API_URL=https://api.zephyrscale.smartbear.com/v2/
+ZEPHYR_API_KEY=your-api-key
+ZEPHYR_TEST_CYCLE_KEY=TEST-CYCLE-123
+```
+
+2. Enable in configuration:
+
+```typescript
+zephyr: {
+  enabled: true,
+  updateResults: true,
+}
+```
+
+3. Run tests - results will be automatically sent to Zephyr!
+
+### How it Works
+
+- Test case keys are extracted from test file names (e.g., `TC-001.spec.ts` → `TC-001`)
+- After test execution, results are sent to Zephyr Scale
+- Test steps are updated with actual results and screenshots
+
+## 🛠️ Project Structure
+
+```
+your-project/
+├── node_modules/
+│   └── @zest-pw/
+│       └── test/          # Installed package
+├── tests/                 # Test files
+│   ├── TC-001.spec.ts
+│   └── TC-002.spec.ts
+├── test-results/          # Test results
+│   └── test-results.json
+├── zest.config.ts         # Zest configuration (auto-created)
+├── playwright.config.ts   # Playwright configuration
+└── package.json
+```
+
+## 📝 Writing Tests
+
+### Basic Test Structure
+
+```typescript
+import { test, expect } from '@zest-pw/test';
+
+test('TC-001: Test description', async ({ page }) => {
+  
+  await test.step('Step 1 description', async () => {
+    // Your test code
+  });
+
+  await test.step('Step 2 description', async () => {
+    // Your test code
+  });
+});
+```
+
+### Test Naming Convention
+
+Name your test files with test case keys for Zephyr integration:
+
+```
+tests/
+├── TC-001.spec.ts   ✅ Good - extracts "TC-001"
+├── TC-002.spec.ts   ✅ Good - extracts "TC-002"
+└── login.spec.ts    ⚠️  Will not sync with Zephyr
+```
+
+### Best Practices
+
+1. **Use descriptive step names** - they become screenshot filenames
+2. **One test per file** - easier to manage and sync with Zephyr
+3. **Keep steps atomic** - each step should be a single action or assertion
+4. **Use test case keys** - for Zephyr integration
+
+## 💡 Commands
+
+```bash
+# Initialize configuration (if not created automatically)
+npx zest-pw-init
+
+# Run all tests
+npx playwright test
+
+# Run specific test
+npx playwright test tests/TC-001.spec.ts
+
+# Run in headed mode
+npx playwright test --headed
+
+# Run in debug mode
+npx playwright test --debug
+
+# Run with UI
+npx playwright test --ui
+
+# Generate Playwright report
+npx playwright show-report
+```
+
+## 🔧 Advanced Usage
+
+### Custom Configuration per Environment
+
+```typescript
+const isDev = process.env.NODE_ENV === 'development';
+const isCI = process.env.CI === 'true';
+
+export default defineZestConfig({
+  reporter: {
+    printToConsole: isDev,
+  },
+  screenshots: {
+    onlyOnFailure: isCI,
+  },
+  zephyr: {
+    enabled: isCI,
+    updateResults: isCI,
+  }
+});
+```
+
+### Accessing Configuration in Code
+
+```typescript
+import { getZestConfig } from '@zest-pw/test';
+
+const config = getZestConfig();
+console.log('Screenshots enabled:', config.screenshots.enabled);
+```
+
+### Programmatic Configuration
+
+```typescript
+import { defineZestConfig } from '@zest-pw/test';
+
+export default defineZestConfig({
+  reporter: {
+    saveJsonReport: process.env.SAVE_REPORTS !== 'false',
+    outputDir: process.env.REPORT_DIR || 'test-results',
+  }
+});
+```
+
+## 🐛 Troubleshooting
+
+### Configuration file not created automatically
+
+If `zest.config.ts` wasn't created after installation, run:
+
+```bash
+npx zest-pw-init
+```
+
+Or create it manually using the template from the Configuration section.
+
+### Screenshots not appearing in report
+
+Check your configuration:
+```typescript
+screenshots: {
+  enabled: true,
+  includeInReport: true,
+}
+```
+
+### Zephyr integration not working
+
+1. Verify environment variables are set
+2. Check test case keys match Zephyr format
+3. Enable Zephyr in configuration
+4. Check API credentials and permissions
+
+### JSON report not saved
+
+Ensure configuration allows saving:
+```typescript
+reporter: {
+  saveJsonReport: true,
+}
+```
+
+### Import errors
+
+Make sure you're importing from the installed package:
+
+```typescript
+// ✅ Correct
+import { test, expect, defineZestConfig } from '@zest-pw/test';
+
+// ❌ Incorrect (old local paths)
+import { test, expect } from './zest-pw/fixtures/fixtures';
+```
+
+## 📚 Documentation
+
+- [Configuration Guide](./CONFIG.md) - Detailed configuration options
+- [Playwright Documentation](https://playwright.dev/) - Official Playwright docs
+- [Zephyr Scale API](https://support.smartbear.com/zephyr-scale-cloud/api-docs/) - Zephyr API reference
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## 📄 License
+
+MIT License - see LICENSE file for details

package/dist/config.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Zest Playwright Configuration
+ *
+ * This file contains configuration options for the Zest Playwright test framework.
+ * You can customize test reporting, screenshot behavior, and Zephyr integration.
+ */
+export interface ZestConfig {
+    /**
+     * Reporter settings
+     */
+    reporter?: {
+        /**
+         * Save test results to JSON file
+         * @default true
+         */
+        saveJsonReport?: boolean;
+        /**
+         * Output directory for JSON reports
+         * @default 'test-results'
+         */
+        outputDir?: string;
+        /**
+         * Print test results to console
+         * @default false
+         */
+        printToConsole?: boolean;
+        /**
+         * Print verbose output (includes all step details)
+         * @default false
+         * @todo Not yet implemented - reserved for future use
+         */
+        verbose?: boolean;
+    };
+    /**
+     * Screenshot settings
+     */
+    screenshots?: {
+        /**
+         * Enable screenshot capture
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Include screenshots in JSON report
+         * @default true
+         */
+        includeInReport?: boolean;
+        /**
+         * Capture screenshots only on failure
+         * @default false
+         */
+        onlyOnFailure?: boolean;
+        /**
+         * Save screenshots to disk as files
+         * @default false
+         */
+        saveToDisk?: boolean;
+    };
+    /**
+     * Zephyr Scale integration settings
+     */
+    zephyr?: {
+        /**
+         * Enable Zephyr Scale integration
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Zephyr API URL
+         */
+        apiUrl?: string;
+        /**
+         * Zephyr API key (recommended to use environment variable)
+         */
+        apiKey?: string;
+        /**
+         * Test Cycle Key
+         */
+        testCycleKey?: string;
+        /**
+         * Update test results in Zephyr after test run
+         * @default false
+         */
+        updateResults?: boolean;
+    };
+}
+/**
+ * Default Zest configuration
+ */
+export declare const defaultConfig: Required<ZestConfig>;
+/**
+ * Define Zest configuration
+ *
+ * @param config - User configuration object
+ * @returns Merged configuration
+ *
+ * @example
+ * ```typescript
+ * export default defineZestConfig({
+ *   reporter: {
+ *     saveJsonReport: true,
+ *     printToConsole: true,
+ *   },
+ *   screenshots: {
+ *     enabled: true,
+ *     onlyOnFailure: true,
+ *   },
+ *   zephyr: {
+ *     enabled: true,
+ *     updateResults: true,
+ *   }
+ * });
+ * ```
+ */
+export declare function defineZestConfig(config: ZestConfig): Required<ZestConfig>;
+/**
+ * Get current Zest configuration
+ *
+ * @returns Current configuration
+ */
+export declare function getZestConfig(): Required<ZestConfig>;
+/**
+ * Load Zest configuration from file
+ * Looks for zest.config.ts in the root directory
+ */
+export declare function loadZestConfig(): Promise<Required<ZestConfig>>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,QAAQ,CAAC,EAAE;QACT;;;WAGG;QACH,cAAc,CAAC,EAAE,OAAO,CAAC;QAEzB;;;WAGG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB;;;WAGG;QACH,cAAc,CAAC,EAAE,OAAO,CAAC;QAEzB;;;;WAIG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IAEF;;OAEG;IACH,WAAW,CAAC,EAAE;QACZ;;;WAGG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC;QAElB;;;WAGG;QACH,eAAe,CAAC,EAAE,OAAO,CAAC;QAE1B;;;WAGG;QACH,aAAa,CAAC,EAAE,OAAO,CAAC;QAExB;;;WAGG;QACH,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB,CAAC;IAEF;;OAEG;IACH,MAAM,CAAC,EAAE;QACP;;;WAGG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC;QAElB;;WAEG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB;;WAEG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB;;WAEG;QACH,YAAY,CAAC,EAAE,MAAM,CAAC;QAEtB;;;WAGG;QACH,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,UAAU,CAoB9C,CAAC;AAOF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC,CAiBzE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,QAAQ,CAAC,UAAU,CAAC,CAEpD;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAcpE"}

package/dist/config.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Zest Playwright Configuration
+ *
+ * This file contains configuration options for the Zest Playwright test framework.
+ * You can customize test reporting, screenshot behavior, and Zephyr integration.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfig = void 0;
+exports.defineZestConfig = defineZestConfig;
+exports.getZestConfig = getZestConfig;
+exports.loadZestConfig = loadZestConfig;
+/**
+ * Default Zest configuration
+ */
+exports.defaultConfig = {
+    reporter: {
+        saveJsonReport: true,
+        outputDir: 'test-results',
+        printToConsole: false,
+        verbose: false,
+    },
+    screenshots: {
+        enabled: true,
+        includeInReport: true,
+        onlyOnFailure: false,
+        saveToDisk: false,
+    },
+    zephyr: {
+        enabled: false,
+        apiUrl: process.env.ZEPHYR_API_URL || '',
+        apiKey: process.env.ZEPHYR_API_KEY || '',
+        testCycleKey: process.env.ZEPHYR_TEST_CYCLE_KEY || '',
+        updateResults: false,
+    },
+};
+/**
+ * Loaded configuration (merged with defaults)
+ */
+let loadedConfig = { ...exports.defaultConfig };
+/**
+ * Define Zest configuration
+ *
+ * @param config - User configuration object
+ * @returns Merged configuration
+ *
+ * @example
+ * ```typescript
+ * export default defineZestConfig({
+ *   reporter: {
+ *     saveJsonReport: true,
+ *     printToConsole: true,
+ *   },
+ *   screenshots: {
+ *     enabled: true,
+ *     onlyOnFailure: true,
+ *   },
+ *   zephyr: {
+ *     enabled: true,
+ *     updateResults: true,
+ *   }
+ * });
+ * ```
+ */
+function defineZestConfig(config) {
+    loadedConfig = {
+        reporter: {
+            ...exports.defaultConfig.reporter,
+            ...config.reporter,
+        },
+        screenshots: {
+            ...exports.defaultConfig.screenshots,
+            ...config.screenshots,
+        },
+        zephyr: {
+            ...exports.defaultConfig.zephyr,
+            ...config.zephyr,
+        },
+    };
+    return loadedConfig;
+}
+/**
+ * Get current Zest configuration
+ *
+ * @returns Current configuration
+ */
+function getZestConfig() {
+    return loadedConfig;
+}
+/**
+ * Load Zest configuration from file
+ * Looks for zest.config.ts in the root directory
+ */
+async function loadZestConfig() {
+    try {
+        const configPath = process.cwd() + '/zest.config.ts';
+        const userConfig = await Promise.resolve(`${configPath}`).then(s => __importStar(require(s)));
+        if (userConfig.default) {
+            return userConfig.default;
+        }
+        return loadedConfig;
+    }
+    catch (error) {
+        // Config file not found or error loading - use defaults
+        return loadedConfig;
+    }
+}

package/dist/fixtures/fixtures.d.ts

@@ -0,0 +1,3 @@
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect } from '@playwright/test';
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/fixtures/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../fixtures/fixtures.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,IAAI,6OAUf,CAAC;AASH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}