OpenBrowse (obrowse)

Introduction

OpenBrowse, or obrowse, is a command-line interface (CLI) tool designed to simplify web browsing tasks directly from your terminal. Whether you need to open specific URLs, generate PDFs of webpages, simulate different browsing environments, or record browser sessions, obrowse provides a convenient solution. Built for Linux environments with cross-browser support including WebKit/Safari testing capabilities.

Installation

Prerequisites

Before installing obrowse, ensure you have the following prerequisites:

• Linux Environment: obrowse is designed for Linux environments. It may work in other Unix-like systems including WSL2, but Linux is the primary target platform.
• Node.js: Node.js is required to run the obrowse CLI tool. If you haven't already installed Node.js, you can download and install it from the Node.js official website.

Installation Steps

1. Clone the Repository:

   Begin by cloning the obrowse repository to your local machine:

   git clone https://github.com/erelsop/obrowse.git ~/src/obrowse
   cd ~/src/obrowse

2. Install Dependencies:

   Install all project dependencies and build the distributable version:

   npm install
   npm run build
   npm run install-browsers

   To install system dependencies required for Playwright, run:

   npm run install-deps

3. Global Access via Symlink or Bash Function:

   Option A: Symlink (Recommended)

   sudo ln -s $(pwd)/dist/obrowse.js /usr/local/bin/obrowse
   chmod +x dist/obrowse.js

   Option B: Bash Function For convenient access to obrowse from anywhere in your terminal, you can define a Bash function in your .bashrc or .zshrc file:

   echo "obrowse() { node ~/src/obrowse/dist/obrowse.js \"\$@\" }" >> ~/.bashrc
   source ~/.bashrc

Usage

Basic Commands

Use obrowse followed by the desired command-line arguments to perform various tasks. Here are some basic commands:

• Open a URL:

  obrowse --browser chrome --url "https://example.com"

• Generate PDF:

  obrowse --browser chrome --url "https://example.com" --headless --pdf "webpage.pdf"

Advanced Options

obrowse supports advanced options for customizing your browsing experience, including:

• PDF Generation: Generate PDFs of web pages with custom format and orientation.
• Custom Resolution and User-Agent: Simulate different devices by specifying custom resolutions and user-agent strings.
• Browser Session Recording: Record browser sessions into video files, useful for bug reporting and tutorials.
• Proxy Support: Specify a proxy server for the browser session, aiding in testing geo-specific content or privacy-focused browsing.
• Configuration File Support: Use a configuration file to save commonly used settings, streamlining the process of initiating browser sessions.
• Headless Mode: Run browsers in headless mode without a visible UI, useful for CI/CD environments and automated testing.
• Integrated Testing: Run automated browser tests using Jest or Mocha directly through the CLI. This feature allows users to specify a testing framework and test files for automated testing alongside their web browsing tasks.
• Cross-Browser Testing: Test your applications in Chrome, Firefox, and WebKit/Safari environments on Linux.

For detailed usage instructions and available options, refer to the command-line help accessible via obrowse --help.

Integrated Testing with Jest and Mocha

obrowse now supports integrated testing, allowing users to run automated tests for their web applications using Jest and Mocha directly through the CLI. This feature simplifies the process of setting up and executing browser-based tests, making it easier to incorporate into your development workflow.

Setting Up Tests

To utilize the testing functionality, ensure your tests are prepared in either Jest or Mocha. Specify the testing framework and the test file path using the --testFrame and --testFile command-line arguments, respectively.

For Jest:

Ensure Jest is installed in your project, and write your tests as you normally would. For example:

const { chromium } = require('playwright');

describe('Google Page Test with Jest', () => {
  it('should open google.com and check the title', async () => {
    const browser = await chromium.launch();
    const page = await browser.newPage();
    await page.goto('https://google.com');
    expect(await page.title()).toBe('Google');
    await browser.close();
  });
});

For Mocha:

For Mocha users, ensure Mocha and Chai are included in your project for testing and assertions. When writing Mocha tests, it's important to note that tests using ES Module syntax should use the .mjs extension or configure Mocha to work with ES Module syntax in .js files:

import { expect } from 'chai';
import { chromium } from 'playwright';

describe('Google Page Test with Mocha', function() {
  it('should open google.com and check the title', async function() {
    const browser = await chromium.launch();
    const page = await browser.newPage();
    await page.goto('https://google.com');
    const title = await page.title();
    expect(title).to.equal('Google');
    await browser.close();
  });
});

Running Tests

To run your tests through obrowse, use the following command, replacing <framework> with either jest or mocha, and <path_to_test_file> with the path to your test file:

obrowse --testFrame <framework> --testFile <path_to_test_file>

Example using Jest:

obrowse --testFrame jest --testFile "./tests/googleJest.test.js"

Example using Mocha:

obrowse --testFrame mocha --testFile "./tests/googleMocha.test.mjs"

Running Tests

The project includes a comprehensive test suite to verify functionality. To run the tests:

# Build the project first
npm run build

# Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run only integration tests
npm run test:integration

# Run only end-to-end tests
npm run test:e2e

# Generate test coverage report
npm run test:coverage

Test Coverage

The test suite includes:

1. Unit Tests:

   • Configuration file handling and validation
   • Case conversion functionality
   • Argument parsing
   • Configuration loading and verification

2. Integration Tests:

   • Browser functionality validation (launching, headless mode, proxy)
   • PDF generation capabilities
   • Test framework integration (Jest and Mocha adapters)

3. End-to-End Tests:

   • CLI functionality validation
   • Configuration file handling
   • Error reporting

All tests are written using Jest with TypeScript, following the naming convention *.test.ts.

Contributing

Contributions to obrowse are welcome! If you're interested in adding features, fixing bugs, or improving the tool, please feel free to fork the repository, make your changes, and submit a pull request.