playwright-test-explorer 0.0.1

package/README.md

@@ -0,0 +1,363 @@
+# Playwright Test Explorer
+
+A CLI tool and library for exploring Playwright tests. This tool provides easy access to test structure, test files, and test cases in your Playwright projects.
+
+## Features
+
+- 📋 List all test files in a Playwright project
+- 🔍 List test cases with detailed information (location, tags, annotations)
+- 🌳 Display test structure as a tree
+- 💻 Easy-to-use CLI interface
+- 📦 Can be used as a library in your Node.js projects
+
+## Installation
+
+### Global Installation
+
+```bash
+npm install -g playwright-test-explorer
+# or
+pnpm add -g playwright-test-explorer
+# or
+yarn global add playwright-test-explorer
+```
+
+### Local Installation
+
+```bash
+npm install playwright-test-explorer
+# or
+pnpm add playwright-test-explorer
+# or
+yarn add playwright-test-explorer
+```
+
+## CLI Usage
+
+### List Test Files
+
+List all test files in the Playwright project:
+
+```bash
+pw-test-explorer list-files
+```
+
+With custom workspace and config:
+
+```bash
+pw-test-explorer list-files -w /path/to/project -c e2e/playwright.config.ts
+```
+
+Save results to a JSON file:
+
+```bash
+pw-test-explorer list-files -o output.json
+```
+
+Options:
+- `-w, --workspace <path>` - Workspace folder path (default: current directory)
+- `-c, --config <file>` - Config file path relative to workspace (default: `playwright.config.ts`)
+- `-o, --output <file>` - Output file path to save JSON results (optional)
+
+### List Test Cases
+
+List all test cases in specified files:
+
+```bash
+pw-test-explorer list-tests -f tests/example.spec.ts tests/another.spec.ts
+```
+
+With custom workspace:
+
+```bash
+pw-test-explorer list-tests -w /path/to/project -f e2e/tests/example.spec.ts
+```
+
+Save results to a JSON file:
+
+```bash
+pw-test-explorer list-tests -f tests/example.spec.ts -o tests.json
+```
+
+Options:
+- `-w, --workspace <path>` - Workspace folder path (default: current directory)
+- `-c, --config <file>` - Config file path relative to workspace (default: `playwright.config.ts`)
+- `-f, --files <files...>` - Test file paths relative to workspace (required)
+- `-o, --output <file>` - Output file path to save JSON results (optional)
+
+### Display Test Tree
+
+Display the complete test structure as a tree:
+
+```bash
+pw-test-explorer tree
+```
+
+With custom workspace:
+
+```bash
+pw-test-explorer tree -w /path/to/project -c playwright.config.ts
+```
+
+Save results to a JSON file:
+
+```bash
+pw-test-explorer tree -o tree.json
+```
+
+Options:
+- `-w, --workspace <path>` - Workspace folder path (default: current directory)
+- `-c, --config <file>` - Config file path relative to workspace (default: `playwright.config.ts`)
+- `-o, --output <file>` - Output file path to save JSON results (optional)
+
+## Library Usage
+
+This package provides three simple APIs for exploring Playwright tests:
+
+```typescript
+import {
+  listTestFile,
+  listTestCase,
+  treeStructure
+} from 'playwright-test-explorer';
+
+// 1. List all test files in a project (output to console)
+await listTestFile('/path/to/project', 'playwright.config.ts');
+
+// List all test files and save to a file
+await listTestFile('/path/to/project', 'playwright.config.ts', 'output.json');
+
+// 2. List test cases in specific files (output to console)
+await listTestCase(
+  '/path/to/project',
+  'playwright.config.ts',
+  ['tests/example.spec.ts', 'tests/another.spec.ts']
+);
+
+// List test cases and save to a file
+await listTestCase(
+  '/path/to/project',
+  'playwright.config.ts',
+  ['tests/example.spec.ts', 'tests/another.spec.ts'],
+  'tests.json'
+);
+
+// 3. Display complete test structure as a tree (output to console)
+await treeStructure('/path/to/project', 'playwright.config.ts');
+
+// Display test tree and save to a file
+await treeStructure(
+  '/path/to/project',
+  'playwright.config.ts',
+  undefined, // cancellationToken
+  'tree.json'
+);
+```
+
+All three functions output results in JSON format - either to `console.log` or to a specified file.
+
+## API Reference
+
+### `listTestFile(workspaceFolder, configFile, outputFile?)`
+
+Lists all test files in the Playwright project and outputs the result to console or a file.
+
+**Parameters:**
+- `workspaceFolder`: `string` - Path to the workspace folder (default: `process.cwd()`)
+- `configFile`: `string` - Config file path relative to workspace (default: `'playwright.config.ts'`)
+- `outputFile`: `string` (optional) - Path to save JSON output. If not provided, outputs to console.
+
+**Returns:** `Promise<void>`
+
+**Output Example:**
+```json
+{
+  "projects": [
+    {
+      "name": "chromium",
+      "testDir": "/path/to/tests",
+      "use": { "browserName": "chromium" },
+      "files": [
+        "/path/to/tests/example.spec.ts",
+        "/path/to/tests/another.spec.ts"
+      ]
+    }
+  ]
+}
+```
+
+### `listTestCase(workspaceFolder, configFile, relativePaths, outputFile?)`
+
+Lists all test cases in specified files and outputs the result to console or a file.
+
+**Parameters:**
+- `workspaceFolder`: `string` - Path to the workspace folder (default: `process.cwd()`)
+- `configFile`: `string` - Config file path relative to workspace (default: `'playwright.config.ts'`)
+- `relativePaths`: `string[]` - Array of test file paths relative to workspace
+- `outputFile`: `string` (optional) - Path to save JSON output. If not provided, outputs to console.
+
+**Returns:** `Promise<void>`
+
+**Output Example:**
+```json
+{
+  "tests": [
+    {
+      "title": "should login successfully",
+      "file": "/path/to/tests/login.spec.ts",
+      "line": 10,
+      "column": 3,
+      "tags": ["@smoke"],
+      "annotations": [],
+      "expectedStatus": "passed",
+      "timeout": 30000,
+      "titlePath": ["Login Tests", "should login successfully"]
+    }
+  ]
+}
+```
+
+### `treeStructure(workspaceFolder, configFile, cancellationToken?, outputFile?)`
+
+Displays the complete test structure as a tree and outputs the result to console or a file.
+
+**Parameters:**
+- `workspaceFolder`: `string` - Path to the workspace folder (default: `process.cwd()`)
+- `configFile`: `string` - Config file path relative to workspace (default: `'playwright.config.ts'`)
+- `cancellationToken`: `CancellationToken` (optional) - Optional cancellation token for cancelling the operation
+- `outputFile`: `string` (optional) - Path to save JSON output. If not provided, outputs to console.
+
+**Returns:** `Promise<void>`
+
+**Output Example:**
+```json
+{
+  "type": "suite",
+  "title": "Root",
+  "children": [
+    {
+      "type": "suite",
+      "title": "Login Tests",
+      "file": "/path/to/tests/login.spec.ts",
+      "children": [
+        {
+          "type": "test",
+          "title": "should login successfully",
+          "location": {
+            "file": "/path/to/tests/login.spec.ts",
+            "line": 10,
+            "column": 3
+          },
+          "tags": ["@smoke"],
+          "expectedStatus": "passed",
+          "timeout": 30000
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Requirements
+
+- Node.js 16 or higher
+- `@playwright/test` installed in your project
+
+## Testing
+
+The project includes comprehensive tests using Vitest and an example Playwright project.
+
+### Run All Tests
+
+```bash
+# Install dependencies and build
+pnpm install
+pnpm run build
+
+# Run vitest tests (includes API and CLI tests)
+pnpm test
+
+# Run tests in watch mode
+pnpm test -- --watch
+
+# Run with coverage
+pnpm test -- --coverage
+```
+
+### Example Project
+
+The `example/` directory contains a sample Playwright project with:
+- 4 projects (chromium, firefox, webkit, mobile)
+- 3 test files with 18+ tests
+- Various test scenarios (UI, API, authentication)
+
+### Test Suites
+
+The project includes two comprehensive test suites:
+
+1. **API Tests** (`tests/api.test.ts`) - Tests the JavaScript API functions
+   - listTestFile functionality
+   - listTestCase functionality
+   - treeStructure functionality
+   - File output capabilities
+
+2. **CLI Tests** (`tests/cli.test.ts`) - Tests the command-line interface
+   - list-files command
+   - list-tests command
+   - tree command
+   - Help and version commands
+   - File output functionality
+
+All tests use the example Playwright project in `example/` directory.
+
+### Manual Testing
+
+```bash
+# List test files
+pnpm run test:list-files
+
+# List test cases
+pnpm run test:list-tests
+
+# Display test tree
+pnpm run test:example
+
+# Save results to files
+pnpm run test:save-files
+pnpm run test:save-tree
+```
+
+See [TESTING.md](TESTING.md) for comprehensive testing documentation.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm run build
+
+# Run in development mode
+pnpm run dev
+
+# Type check
+pnpm run typecheck
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm run test:watch
+
+# Run tests with coverage
+pnpm run test:coverage
+```
+
+## License
+
+MIT
+
+## Credits
+
+Based on the test server implementation from [Microsoft's playwright-vscode](https://github.com/microsoft/playwright-vscode).