BaseScript

A Baseline-Aware Scripting Language for Web Automation with Built-In Feature Compatibility Intelligence

Comment

Inspiration

The inspiration for BaseScript stems directly from the central question posed by the Baseline Tooling Hackathon: "Ever hesitated to use a new feature, wondering, 'Is it safe to use yet?'" As web developers, we constantly face this dilemma. The rapid evolution of the web brings powerful new CSS, HTML, and JavaScript features, but adopting them is fraught with uncertainty about cross-browser compatibility. This "compatibility tax" forces developers to spend countless hours switching between MDN, caniuse.com, and various blog posts, slowing down innovation.

We saw an opportunity to bring this critical compatibility intelligence directly into a phase of the development lifecycle where it matters most: automated testing and QA. Traditional automation scripts are great at testing functionality ("Does the button work?"), but they are completely blind to the underlying technology ("Will the CSS that styles this button work for all our users?").

Our vision was to create a tool that not only simplifies the creation of automation scripts but also enriches them with built-in Baseline awareness. We wanted to build a system where developers and QA teams could get instant, actionable feedback on feature compatibility as an intrinsic part of their existing testing workflows. This would empower teams to adopt modern features confidently, accelerate development, and build more robust, accessible web applications for everyone.

What it does

BaseScript is a comprehensive, Baseline-aware platform for web automation, designed to make feature compatibility visible, actionable, and integral to the testing process. It consists of two main parts: a powerful scripting language and an interactive web-based playground.

1. The BaseScript Language: Users author high-level web automation scripts in a simple, human-readable declarative format using YAML. These scripts are then transpiled into robust, executable Node.js code for the industry's leading automation frameworks: Puppeteer, Playwright, and Selenium. This write-once, run-anywhere approach democratizes test creation, allowing even non-programmers to contribute to the QA process.

2. Baseline Compatibility Intelligence: This is the core innovation of BaseScript. We have integrated Baseline data directly into the automation engine through a special baseline_scan command. When this command is executed during an automation session, BaseScript:

  • Dynamically Scans the Live DOM: It inspects all stylesheets and computed styles on the current webpage.
  • Identifies Non-Baseline Features: It checks every CSS feature against the Baseline data, flagging any properties or values that don't meet the user-defined criteria (e.g., widely available since 2023).
  • Provides Actionable Feedback: Delivers real-time alerts and recommendations, helping developers pinpoint potential compatibility issues before they reach production.

3. The Interactive Playground: BaseScript is delivered through a modern, full-featured web IDE that provides a seamless developer experience:

  • Code Editor: A sophisticated editor with syntax highlighting for writing BaseScript YAML.
  • Live Browser Preview: A real-time VNC connection to the containerized Chrome browser, allowing users to watch their automation scripts execute live.
  • Compiled Code View: Instantly see the transpiled JavaScript output for the selected framework.
  • Screenshot Gallery: Automatically capture, view, manage, and download screenshots taken during test runs.
  • Real-time Terminal: A live feed of logs and output from the script execution process, streamed directly to the browser.

By combining an easy-to-use scripting language with powerful, automated Baseline analysis and a rich interactive environment, BaseScript transforms web automation from a simple functional check into a deep compatibility audit.

How we built it

BaseScript is architected as a set of containerized microservices, orchestrated with Docker Compose for a simple, one-command setup. This architecture ensures scalability, separation of concerns, and a smooth development experience.

  • Architecture: 4 main services working in concert: Playground (Frontend), Compiler (Backend), Browser (Test Environment), and Redis (State Cache).

  • Playground (Frontend):

    • A React (Vite) single-page application that serves as the user's IDE.
    • CodeMirror is used for the YAML and JavaScript editors.
    • React-VNC provides the live, interactive browser preview panel.
    • Socket.IO streams real-time logs from the backend to the terminal component.
    • TailwindCSS for a modern, responsive, and themeable (dark/light) UI.

  • Compiler (Backend):

    • A Node.js/Express server that acts as the brains of the operation.
    • It exposes a REST API to receive BaseScript YAML from the Playground.
    • YAML & Zod: It parses the script using the yaml library and validates its structure against a comprehensive schema defined with zod.
    • Compiler Pipeline: The validated script is converted into an Intermediate Representation (IR). This IR is then passed to a framework-specific handler (PuppeteerHandler, PlaywrightHandler, or SeleniumHandler), which generates the final JavaScript code. This pluggable design makes the system highly extensible.
    • Baseline Integration: The core baseline_scan functionality is implemented here, using the web-features npm package to programmatically access Baseline data and the css-tree package to parse CSS from the browser.
    • Execution Engine: The compiled JavaScript is saved to a file and executed as a child process, with its stdout and stderr streams piped back to the Playground via Socket.IO.

  • Browser:

    • A custom Docker container built on top of the selenium/standalone-chrome image.
    • It includes an X11 VNC server to provide the live preview stream.
    • A Caddy reverse proxy is used to manage access to the Chrome DevTools Protocol port.
    • A custom monitor_chrome.sh shell script continuously checks the browser's status and publishes its dynamic WebSocket Debugger URL to Redis, enabling the Compiler to connect reliably.

  • Redis:

    • Acts as a fast in-memory data store for state management and service discovery. Its primary role is to hold the current WebSocket URL of the Chrome browser, decoupling the Compiler and Browser services.

Challenges we ran into

  1. Dynamic Service Discovery: A major challenge was enabling the Compiler service to connect to the Browser service in connect mode. The browser's WebSocket URL is dynamic and not known at build time. We solved this by creating a custom monitoring script inside the browser container that polls for the URL and publishes it to a known key in Redis. The Compiler can then query Redis to get the correct, live endpoint.

  2. Implementing the Baseline Scanner: The logic for scanning a live webpage for non-baseline features was complex. It required programmatically executing scripts within the browser context to extract all CSS from stylesheets and computed styles, parsing it efficiently using css-tree, and then cross-referencing thousands of properties against the data structure of the web-features package. Presenting this data back to the user in a clear and actionable way remains an ongoing design challenge.

  3. Abstracting Framework Differences: Designing a single Intermediate Representation (IR) that could successfully compile to Puppeteer, Playwright, and Selenium was difficult. While they share many concepts, their APIs have subtle but important differences in syntax, options, and capabilities (e.g., device emulation, assertion methods). We overcame this by creating a robust handler-based architecture where each framework's unique logic is encapsulated in its own class.

Accomplishments that we're proud of

  • True Baseline Integration: We successfully built a tool that directly addresses the hackathon's core mission. BaseScript doesn't just show compatibility data; it integrates it directly into a dynamic, automated workflow, providing insights at the exact moment they are needed.
  • A Complete, Polished Platform: We are incredibly proud of the seamless user experience of the BaseScript Playground. The combination of the editor, live VNC preview, screenshot gallery, and terminal into one cohesive and aesthetically pleasing interface is a major accomplishment.
  • Multi-Framework Compiler Engine: The flexible compiler design that supports three major automation frameworks from a single, simple YAML syntax is a powerful feature that makes the tool incredibly versatile and valuable to a wide range of developers.
  • Robust Microservices Architecture: The clean, fully containerized docker-compose setup makes the entire platform portable, scalable, and incredibly easy for anyone to run with a single command.

What we learned

  • The Power of Programmatic Baseline: We gained a deep understanding of how to leverage the web-features npm package as a powerful engine for building developer tools. We learned how to query it effectively to build the kind of automated compatibility intelligence we envisioned.
  • Intricacies of Browser Automation: Implementing the handlers for Puppeteer, Playwright, and Selenium gave us a profound appreciation for the nuances and comparative strengths of each framework.
  • Full-Stack and DevOps Skills: This project was a true full-stack endeavor. We honed our skills across modern frontend development with React, backend API design with Node.js, and complex system orchestration with Docker Compose and Redis.

What's next for BaseScript

The roadmap for BaseScript is exciting, with a focus on expanding its intelligence and reach.

  • Expand Baseline Support: The next logical step is to add scanners for HTML elements/attributes and JavaScript APIs, providing a complete 360-degree view of a web application's feature compatibility.
  • Enhanced Reporting and Visualization: We plan to build a dedicated "Baseline Report" dashboard that visualizes the results of a scan, showing exactly which non-baseline features were found, which DOM elements they affect, and offering direct links to documentation and potential polyfills.
  • Visual Script Builder: To further democratize automation, we envision a drag-and-drop interface that allows users to build BaseScript workflows visually, without writing any code.
  • True Cross-Browser Testing: We will add support for Firefox, Safari, and Edge containers, allowing users to run the same script across multiple browsers and compare compatibility results side-by-side.
  • CI/CD Integration: We will improve the CLI and create dedicated GitHub Actions or other CI plugins to allow teams to run BaseScript compatibility audits as a required check in their deployment pipelines.

Built With

  • docker-compose
  • node.js
  • playwright
  • puppeteer
  • selenium
  • web-automation-baseline-check
  • web-features
Share this project:

Updates