twd-cli 1.0.1

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,63 @@
+---
+name: Bug Report
+about: Create a report to help us improve TWD
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear and concise description of what the bug is.
+
+## Environment Information
+
+Please provide the following information to help us reproduce the issue:
+
+### Framework & Build Tool
+- **Framework**: [e.g., React, Astro, Remix]
+- **Build Tool**: [e.g., Vite, Webpack, Create React App]
+- **Framework Version**: [e.g., React 18.2.0]
+
+### Runtime Environment
+- **Node Version**: [e.g., 20.10.0]
+- **npm/yarn/pnpm Version**: [e.g., npm 10.2.0]
+- **Browser**: [e.g., Chrome 120, Firefox 121, Safari 17]
+- **Browser Version**: [e.g., 120.0.6099.109]
+
+### TWD Version
+- **twd-js Version**: [e.g., 1.2.3]
+
+## How to Reproduce
+
+1. How do you run your tests? [e.g., `npm run dev`, `vite`, `npm start`]
+2. What command do you use to start your development server?
+3. Steps to reproduce the behavior:
+   - Step 1: ...
+   - Step 2: ...
+   - Step 3: ...
+
+## Test Code
+
+**Please paste your complete test file(s) here:**
+
+## Expected Behavior
+
+A clear and concise description of what you expected to happen.
+
+## Actual Behavior
+
+A clear and concise description of what actually happened.
+
+## Screenshots
+
+If applicable, add screenshots to help explain your problem. Screenshots are **highly appreciated** and help us understand the issue better.
+
+## Additional Context
+
+Add any other context about the problem here. For example:
+
+## Possible Solution
+
+If you have ideas on how to fix this, please share them here (optional).
+

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,52 @@
+---
+name: Feature Request
+about: Suggest an idea for TWD cli
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+
+A clear and concise description of the feature you'd like to see.
+
+## Why is this feature needed?
+
+Explain the problem or use case this feature would solve. What pain point does it address?
+
+## Proposed Solution
+
+Describe how you envision this feature working. Be as detailed as possible.
+
+### API/Interface Design
+
+How would developers use this feature? Please provide example code:
+
+### Implementation Approach
+
+If you have ideas on how this could be implemented, please share them here.
+
+## Breaking Changes
+
+- [ ] This feature would introduce breaking changes
+- [ ] This feature would be backward compatible
+
+If breaking changes are involved, please explain:
+- What would break?
+- How would migration work?
+- What's the deprecation path?
+
+## Testing Strategy
+
+How would this feature be tested? Please describe:
+- What test scenarios should be covered?
+- How would we verify it works correctly?
+- Are there edge cases to consider?
+
+## Benefits
+
+What benefits would this feature bring to TWD users?
+- Performance improvements?
+- Better developer experience?
+- New capabilities?
+- Easier testing workflows?

package/.github/pull_request_template.md

@@ -0,0 +1,43 @@
+## Description
+
+Please include a summary of the changes and the related issue. Include relevant motivation and context.
+
+Fixes # (issue)
+
+## Type of Change
+
+Please delete options that are not relevant:
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Code refactoring
+- [ ] Performance improvement
+- [ ] Test addition or update
+
+## Testing
+
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] All existing tests pass
+- [ ] New and existing unit tests pass locally
+- [ ] I have tested this change manually
+
+**Note**: Pull requests without tests will not be reviewed. Please ensure you've added appropriate test coverage.
+
+### Test Details
+
+Describe the tests you've added or updated:
+
+
+## Documentation
+
+- [ ] I have updated the documentation accordingly
+- [ ] I have added/updated code comments where necessary
+- [ ] The changes are reflected in the relevant documentation files
+
+**Note**: If your change affects the public API or adds new features, documentation updates are required.
+
+## Screenshots (if applicable)
+
+If your changes affect the UI or add visual features, please add screenshots:

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org/
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BRIKEV
+
+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,82 @@
+# twd-cli
+
+CLI tool for running TWD (Test with Documentation) tests using Puppeteer in CI/CD environments.
+
+## Installation
+
+```bash
+npm install twd-cli
+```
+
+Or use directly with npx:
+
+```bash
+npx twd-cli run
+```
+
+## Usage
+
+### Basic Usage
+
+Run tests with default configuration:
+
+```bash
+npx twd-cli run
+```
+
+### Configuration
+
+Create a `twd.config.json` file in your project root to customize settings:
+
+```json
+{
+  "url": "http://localhost:5173",
+  "timeout": 10000,
+  "coverage": true,
+  "coverageDir": "./coverage",
+  "nycOutputDir": "./.nyc_output",
+  "headless": true,
+  "puppeteerArgs": ["--no-sandbox", "--disable-setuid-sandbox"]
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | string | `"http://localhost:5173"` | The URL of your development server |
+| `timeout` | number | `10000` | Timeout in milliseconds for page load |
+| `coverage` | boolean | `true` | Enable/disable code coverage collection |
+| `coverageDir` | string | `"./coverage"` | Directory to store coverage reports |
+| `nycOutputDir` | string | `"./.nyc_output"` | Directory for NYC output |
+| `headless` | boolean | `true` | Run browser in headless mode |
+| `puppeteerArgs` | string[] | `["--no-sandbox", "--disable-setuid-sandbox"]` | Additional Puppeteer launch arguments |
+
+## How It Works
+
+1. Launches a Puppeteer browser instance
+2. Navigates to your specified URL
+3. Waits for your app to be ready
+4. Executes all TWD tests via `window.__testRunner`
+5. Collects and reports test results
+6. Optionally collects code coverage data
+7. Exits with appropriate code (0 for success, 1 for failures)
+
+## CI/CD Integration
+
+The CLI exits with code 1 if any tests fail, making it perfect for CI/CD pipelines:
+
+```yaml
+# Example GitHub Actions workflow
+- name: Run TWD Tests
+  run: npx twd-cli run
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- A running development server with TWD tests
+
+## License
+
+ISC

package/bin/twd-cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { runTests } from '../src/index.js';
+
+const command = process.argv[2];
+
+if (command === 'run') {
+  try {
+    await runTests();
+  } catch (error) {
+    console.error('Error running tests:', error);
+    process.exit(1);
+  }
+} else {
+  console.log(`
+twd-cli - Test runner for TWD tests
+
+Usage:
+  npx twd-cli run    Run all tests
+
+Options:
+  Create a twd.config.json file in your project root to customize settings.
+  `);
+  process.exit(command ? 1 : 0);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "twd-cli",
+  "version": "1.0.1",
+  "description": "CLI tool for running TWD tests with Puppeteer",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "twd-cli": "./bin/twd-cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "execute:cli": "node ./bin/twd-cli.js"
+  },
+  "keywords": [
+    "twd",
+    "testing",
+    "cli",
+    "puppeteer",
+    "browser-testing"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "puppeteer": "^24.31.0",
+    "twd-js": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,29 @@
+import fs from 'fs';
+import path from 'path';
+
+const DEFAULT_CONFIG = {
+  url: 'http://localhost:5173',
+  timeout: 10000,
+  coverage: true,
+  coverageDir: './coverage',
+  nycOutputDir: './.nyc_output',
+  headless: true,
+  puppeteerArgs: ['--no-sandbox', '--disable-setuid-sandbox'],
+};
+
+export function loadConfig() {
+  const configPath = path.resolve(process.cwd(), 'twd.config.json');
+  
+  if (fs.existsSync(configPath)) {
+    try {
+      const configFile = fs.readFileSync(configPath, 'utf-8');
+      const userConfig = JSON.parse(configFile);
+      return { ...DEFAULT_CONFIG, ...userConfig };
+    } catch (error) {
+      console.warn('Warning: Could not parse twd.config.json, using defaults:', error.message);
+      return DEFAULT_CONFIG;
+    }
+  }
+  
+  return DEFAULT_CONFIG;
+}

package/src/index.js

@@ -0,0 +1,78 @@
+import fs from 'fs';
+import path from 'path';
+import puppeteer from 'puppeteer';
+import { reportResults, executeTests } from 'twd-js/runner-ci';
+import { loadConfig } from './config.js';
+
+export async function runTests() {
+  const config = loadConfig();
+  const workingDir = process.cwd();
+
+  console.log('Starting TWD test runner...');
+  console.log('Configuration:', JSON.stringify(config, null, 2));
+
+  const browser = await puppeteer.launch({
+    headless: config.headless,
+    args: config.puppeteerArgs,
+  });
+
+  const page = await browser.newPage();
+  console.time('Total Test Time');
+
+  try {
+    // Navigate to your development server
+    console.log(`Navigating to ${config.url} ...`);
+    await page.goto(config.url);
+
+    // Wait for the selector to be available
+    await page.waitForSelector("[data-testid=\"twd-sidebar\"]", { timeout: config.timeout });
+    console.log('Page loaded. Starting tests...');
+
+    // Execute all tests
+    const { handlers, testStatus } = await page.evaluate(async () => {
+      return await executeTests();
+    });
+
+    console.log(`Tests to report: ${testStatus.length}`);
+
+    // Display results in console
+    reportResults(handlers, testStatus);
+
+    
+    // Exit with appropriate code
+    const hasFailures = testStatus.some(test => test.status === 'fail');
+    console.timeEnd('Total Test Time');
+    // Handle code coverage if enabled
+    if (config.coverage && !hasFailures) {
+      const coverage = await page.evaluate(() => window.__coverage__);
+      if (coverage) {
+        console.log('Collecting code coverage data...');
+        const coverageDir = path.resolve(workingDir, config.coverageDir);
+        const nycDir = path.resolve(workingDir, config.nycOutputDir);
+
+        if (!fs.existsSync(nycDir)) {
+          fs.mkdirSync(nycDir, { recursive: true });
+        }
+        if (!fs.existsSync(coverageDir)) {
+          fs.mkdirSync(coverageDir, { recursive: true });
+        }
+
+        const coveragePath = path.join(nycDir, 'out.json');
+        fs.writeFileSync(coveragePath, JSON.stringify(coverage));
+        console.log(`Code coverage data written to ${coveragePath}`);
+      } else {
+        console.log('No code coverage data found.');
+      }
+    }
+    
+    await browser.close();
+    console.log('Browser closed.');
+
+    process.exit(hasFailures ? 1 : 0);
+
+  } catch (error) {
+    console.error('Error running tests:', error);
+    await browser.close();
+    process.exit(1);
+  }
+}

package/twd.config.example.json

@@ -0,0 +1,9 @@
+{
+  "url": "http://localhost:5173",
+  "timeout": 10000,
+  "coverage": true,
+  "coverageDir": "./coverage",
+  "nycOutputDir": "./.nyc_output",
+  "headless": true,
+  "puppeteerArgs": ["--no-sandbox", "--disable-setuid-sandbox"]
+}