any-browser 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BhalliBhai
+
+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,131 @@
+# any-browser
+
+Test your website on Chrome, Firefox, and Safari — from any OS — with one command.
+
+```
+any-browser test safari
+any-browser test chrome firefox
+any-browser test all
+```
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Usage](#usage)
+- [What Are The Major Browsers?](#what-are-the-major-browsers)
+- [Running From Source Instead](#running-from-source-instead)
+- [Troubleshooting](#troubleshooting)
+- [Publishing / Releasing](#publishing--releasing) (maintainers)
+
+## Getting Started
+
+Install it globally from npm:
+
+```
+npm install -g any-browser
+```
+
+The first install downloads the Chrome, Firefox, and Safari (WebKit) engines
+via Playwright — that's a one-time ~300MB download, and you'll see exactly
+what's happening and why in your terminal. After that, every run is instant.
+
+## Usage
+
+```
+any-browser test <browser...> [options]
+```
+
+| Browser argument | Engine used |
+|---|---|
+| `chrome` | Chromium |
+| `firefox` | Firefox |
+| `safari` | WebKit |
+| `all` | all three |
+
+Options:
+
+- `-u, --url <url>` — URL to test (default: `http://localhost:3000`)
+- `--headless` — run without opening a visible window
+
+Examples:
+
+```
+any-browser test safari
+any-browser test chrome firefox
+any-browser test all --url https://example.com
+```
+
+🎇 Each browser opens in front of you, paused, so you can click around and
+inspect the page exactly like a real visitor would.
+
+## What Are The Major Browsers?
+
+Ensuring your website looks great across all major browsers is crucial for a
+consistent user experience. `any-browser` covers Chrome, Firefox, and Safari
+regardless of your operating system — Linux, macOS, or Windows.
+
+If we look at browser market share worldwide, Chrome dominates at around 64%,
+Safari follows with about 20%, and Firefox holds roughly 4%. While there are
+many other browsers, these three are critical because they use distinct
+rendering engines:
+
+- **Chrome** (and Chromium-based browsers like Edge and Brave) use **Blink**.
+- **Firefox** uses **Gecko**, developed by Mozilla.
+- **Safari** uses **WebKit**, developed by Apple.
+
+Since Safari is exclusive to macOS, testing it from Linux or Windows normally
+requires workarounds. `any-browser` sidesteps that entirely by using
+Playwright's open-source WebKit build, so `any-browser test safari` works
+identically on any OS.
+
+## Running From Source Instead
+
+Prefer to clone and run it locally rather than install globally? That still
+works exactly like before:
+
+```
+git clone https://github.com/BhalliBhai/any-browser-cli.git
+cd any-browser-cli
+npm install
+npm run test:safari   # or test:chrome / test:firefox
+```
+
+## Troubleshooting
+
+If you hit missing dependencies on Linux when running WebKit tests:
+
+```
+npx playwright install-deps webkit
+```
+
+If you see an error about missing libraries such as:
+
+```
+browserType.launch:
+Host system is missing dependencies to run browsers.
+Missing libraries:
+  libpcre.so.3
+  libicui18n.so.66
+  libicuuc.so.66
+  libwebp.so.6
+  libenchant.so.1
+  libffi.so.
+```
+
+Install the necessary system packages. On Ubuntu/Debian:
+
+```
+sudo apt-get install -y libpcre3 libicu66 libwebp6 libenchant1c2a libffi7
+```
+
+For other distributions, check your package manager's docs, or just run
+`npx playwright install-deps` and let Playwright figure it out.
+
+## Publishing / Releasing
+
+See [PUBLISHING.md](./PUBLISHING.md) for the one-time npm/GitHub setup and the
+release workflow.
+
+---
+
+If this helped, consider starring ⭐ the repository to support the project! 😊

package/bin/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { runTests } from '../src/runner.js';
+import { SUPPORTED_BROWSERS } from '../src/browsers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const program = new Command();
+
+program
+  .name('any-browser')
+  .description('Test your website across Chrome, Firefox, and Safari from one CLI command.')
+  .version(pkg.version, '-v, --version');
+
+program
+  .command('test')
+  .description('Open your site in one or more browsers for testing')
+  .argument(
+    '<browsers...>',
+    `browser(s) to test — ${Object.keys(SUPPORTED_BROWSERS).join(', ')}, or "all"`
+  )
+  .option('-u, --url <url>', 'URL to test', 'http://localhost:3000')
+  .option('--headless', 'run without opening a visible browser window', false)
+  .action(async (browsers, options) => {
+    await runTests(browsers, options);
+  });
+
+program.addHelpText(
+  'after',
+  `
+Examples:
+  $ any-browser test safari
+  $ any-browser test chrome firefox
+  $ any-browser test all
+  $ any-browser test chrome --url https://example.com
+`
+);
+
+program.parse();

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "any-browser",
+  "version": "1.0.0",
+  "description": "Test your website across Chrome, Firefox, and Safari (WebKit) with one CLI command.",
+  "type": "module",
+  "bin": {
+    "any-browser": "./bin/cli.js"
+  },
+  "main": "src/runner.js",
+  "files": [
+    "bin",
+    "src",
+    "playwright.config.js",
+    "tests",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node src/postinstall.js",
+    "test:chrome": "playwright test --project=chromium --headed",
+    "test:firefox": "playwright test --project=firefox --headed",
+    "test:safari": "playwright test --project=webkit --headed"
+  },
+  "keywords": [
+    "cli",
+    "browser-testing",
+    "playwright",
+    "cross-browser",
+    "chrome",
+    "firefox",
+    "safari",
+    "webkit",
+    "qa"
+  ],
+  "author": "BhalliBhai (https://bhalli.dev)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BhalliBhai/any-browser-cli.git"
+  },
+  "homepage": "https://github.com/BhalliBhai/any-browser-cli#readme",
+  "bugs": {
+    "url": "https://github.com/BhalliBhai/any-browser-cli/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@playwright/test": "^1.50.0",
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1"
+  }
+}

package/playwright.config.js

@@ -0,0 +1,23 @@
+import { defineConfig, devices } from '@playwright/test';
+
+// Device presets bundle a fixed viewport + deviceScaleFactor together.
+// We want the real, resizable window instead, so strip both before reapplying.
+function desktop(deviceName) {
+  const { viewport, deviceScaleFactor, ...rest } = devices[deviceName];
+  return rest;
+}
+
+export default defineConfig({
+  testDir: './tests',
+  fullyParallel: false,
+  reporter: 'list',
+  timeout: 0, // no timeout — these tests wait for you to close the window
+  use: {
+    trace: 'off',
+  },
+  projects: [
+    { name: 'chromium', use: { ...desktop('Desktop Chrome'), viewport: null } },
+    { name: 'firefox', use: { ...desktop('Desktop Firefox'), viewport: null } },
+    { name: 'webkit', use: { ...desktop('Desktop Safari'), viewport: null } },
+  ],
+});

package/src/browsers.js

@@ -0,0 +1,39 @@
+export const SUPPORTED_BROWSERS = {
+  chrome: 'chromium',
+  chromium: 'chromium',
+  firefox: 'firefox',
+  safari: 'webkit',
+  webkit: 'webkit',
+};
+
+export const ENGINE_LABELS = {
+  chromium: 'Chrome',
+  firefox: 'Firefox',
+  webkit: 'Safari',
+};
+
+/**
+ * Turns whatever the user typed (["safari", "Chrome", "all"]) into a clean,
+ * deduplicated list of Playwright engine names, plus anything we didn't recognize.
+ */
+export function resolveBrowsers(requested) {
+  const list = requested.map((b) => b.toLowerCase());
+
+  if (list.includes('all')) {
+    return { resolved: ['chromium', 'firefox', 'webkit'], unknown: [] };
+  }
+
+  const resolved = [];
+  const unknown = [];
+
+  for (const name of list) {
+    const engine = SUPPORTED_BROWSERS[name];
+    if (!engine) {
+      unknown.push(name);
+      continue;
+    }
+    if (!resolved.includes(engine)) resolved.push(engine);
+  }
+
+  return { resolved, unknown };
+}

package/src/postinstall.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import pc from 'picocolors';
+
+const isCI = !!process.env.CI;
+
+console.log('');
+console.log(pc.cyan('any-browser needs real browser engines (Chromium, Firefox, WebKit) to run tests.'));
+console.log(
+  pc.dim('This is a one-time download (~300MB total, handled by Playwright) so every')
+);
+console.log(pc.dim('"any-browser test <browser>" run afterwards is instant — no setup needed.'));
+
+if (isCI) {
+  console.log(pc.yellow('\nCI environment detected — skipping the automatic download.'));
+  console.log(pc.dim('Add this as its own step in your CI pipeline instead:'));
+  console.log(pc.bold('  npx playwright install --with-deps\n'));
+  process.exit(0);
+}
+
+console.log(pc.dim('\nDownloading now...\n'));
+
+const result = spawnSync('npx', ['playwright', 'install', 'chromium', 'firefox', 'webkit'], {
+  stdio: 'inherit',
+  shell: process.platform === 'win32',
+});
+
+if (result.status === 0) {
+  console.log(pc.green("\n✓ Browser engines installed. You're ready to go:"));
+  console.log(pc.bold('  any-browser test chrome firefox safari\n'));
+} else {
+  console.log(pc.yellow("\nCouldn't auto-install the browser engines (this can happen behind"));
+  console.log(pc.yellow('certain firewalls/proxies, or if disk space is low).'));
+  console.log(pc.dim('Run this once manually, then you\'re good:'));
+  console.log(pc.bold('  npx playwright install chromium firefox webkit\n'));
+}

package/src/runner.js

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import pc from 'picocolors';
+import { resolveBrowsers, ENGINE_LABELS } from './browsers.js';
+
+export async function runTests(browserArgs, options) {
+  const { resolved, unknown } = resolveBrowsers(browserArgs);
+
+  if (unknown.length) {
+    console.log(pc.yellow(`Skipping unknown browser(s): ${unknown.join(', ')}`));
+    console.log(pc.dim('Supported: chrome, firefox, safari, all'));
+  }
+
+  if (!resolved.length) {
+    console.log(pc.red('No valid browsers to test. Try: any-browser test chrome firefox safari'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const names = resolved.map((e) => ENGINE_LABELS[e]).join(', ');
+  console.log(pc.cyan(`\nTesting ${options.url} in: ${names}\n`));
+
+  for (const engine of resolved) {
+    // eslint-disable-next-line no-await-in-loop -- browsers run one at a time on purpose
+    await runOne(engine, options);
+  }
+}
+
+function runOne(engine, options) {
+  return new Promise((resolve) => {
+    console.log(pc.bold(`\n▶ ${ENGINE_LABELS[engine]} (${engine})`));
+
+    const args = ['playwright', 'test', `--project=${engine}`];
+    if (!options.headless) args.push('--headed');
+
+    const child = spawn('npx', args, {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        TEST_URL: options.url,
+        TEST_HEADLESS: options.headless ? '1' : '0',
+      },
+      shell: process.platform === 'win32',
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        console.log(pc.green(`✓ ${ENGINE_LABELS[engine]} finished`));
+      } else {
+        console.log(pc.red(`✗ ${ENGINE_LABELS[engine]} exited with code ${code}`));
+      }
+      resolve();
+    });
+
+    child.on('error', (err) => {
+      console.log(pc.red(`✗ Couldn't start ${ENGINE_LABELS[engine]}: ${err.message}`));
+      resolve();
+    });
+  });
+}

package/tests/browser.test.ts

@@ -0,0 +1,20 @@
+import { test } from '@playwright/test';
+
+test('open site for manual testing', async ({ page }) => {
+  const url = process.env.TEST_URL || 'http://localhost:3000';
+  const headless = process.env.TEST_HEADLESS === '1';
+
+  await page.goto(url);
+
+  if (headless) {
+    // No window for a human to close in headless mode — just confirm the
+    // page settled, then move on to the next browser.
+    await page.waitForLoadState('networkidle').catch(() => {});
+    return;
+  }
+
+  console.log('\n  Window open — close it when you\'re done to move to the next browser.\n');
+
+  // No Inspector, no pause button to hunt for — closing the window is the signal.
+  await page.waitForEvent('close', { timeout: 0 }).catch(() => {});
+});