Headless Browser setup for Microsoft Windows

  • Release version: Zurich
  • Updated July 31, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Headless Browser setup for Microsoft Windows

    The ServiceNow® Headless Browser for Automated Test Framework (ATF) enables automated testing without the need to manually open a browser. This setup is available for both Linux and Microsoft Windows, with this content specifically covering the Windows setup. Note that Headless Browser is a legacy feature; ServiceNow recommends using the ATF Test Generator and Cloud Runner application for an improved and easier experience. However, on-premise instance users must continue using Headless Browser as Cloud Runner is not yet supported on-premise.

    Show full answer Show less

    Prerequisites

    • Instance Requirements: Multi-Factor Authentication (MFA) must be disabled.
    • User Roles: Admin role on the ServiceNow instance and local administrator on the Windows host machine.
    • Supported OS: Only Windows Server 2019 v10.0.17763.737 is supported. If unable to meet this, consider using a Linux host.
    • Software to Install: Docker, Java keytool (via Chocolatey), and OpenSSL (via Chocolatey) must be installed on the Windows server.
    • Network Configuration: Ensure two-way communication between the ServiceNow instance and the Windows server. The server’s IP address or hostname must be accessible from the instance. Configure firewall rules to allow inbound requests on port 2376 (or custom port) from the instance IP ranges.

    Setup Process

    The setup involves seven sequential steps plus verification to complete the Headless Browser configuration on Windows:

    • Install Docker: Prepare the Windows server with Docker for container management.
    • Generate TLS/SSL Certificates: Create certificates to secure Docker REST API communication and authenticate HTTP requests.
    • Configure Docker Server: Set Docker to require authenticated requests for enhanced security.
    • Create Docker Image and Containers: Pull the necessary Docker image from the public registry and instantiate the containers for the Headless Browser.
    • Add Docker Secrets: Securely store the ServiceNow user password using Docker Secrets for container authentication during test execution.
    • Configure the ServiceNow Instance: Prepare the instance to support the Headless Browser functionality.
    • Configure Automated Test Framework (ATF): Set the required ATF properties to enable and manage Headless Browser usage.

    Verification

    After completing all setup steps, verify that the Headless Browser is properly configured and operational within your Windows environment to ensure automated tests run smoothly without manual browser interaction.

    The ServiceNow® Headless Browser for Automated Test Framework (ATF) provides automation so you can skip having to manually open a browser during testing. The Headless Browser setup is available in both Linux and Microsoft Windows. This topic covers the setup for Windows.

    Important:
    Headless Browser is a legacy feature of ATF; it is recommended to instead use the ATF Test Generator and Cloud Runner application. Cloud Runner offers you an easy setup and a seamless user experience. You can install Cloud Runner from the store app.
    If you are an on-premise instance user, you must continue using the Headless Browser option. Cloud Runner is not currently available for on-premise instances.

    There are several sequential procedures to follow in the one-time setup. Below are the instructions for the Microsoft Windows setup.

    Prerequisites

    Note:
    MFA must be disabled in your instance to use the Headless Browser option.
    Role required: admin on your ServiceNow instance and local administrator on the host machine.
    Warning:
    The only supported version of Microsoft Windows as a host is Windows Server 2019 v10.0.17763.737. No other versions are supported. If you are unable to meet these requirements, a Linux host is recommended.
    • Make sure that the following programs are installed on your Windows server:
    • Two-way communication
      • There must be two-way communication between the instance URL and your server.
      • Find the IP address of your server and get your hostname. You can use one or both of them, but you need at least one. Make sure the address or hostname are visible from your ServiceNow instance.
      • See My IP Address to find the IP address ranges of your instance. You can then configure your server to allow inbound access to all of the indicated IP addresses/ranges.
      • Use Port 2376 or your own default port for this procedure. Make sure your server's firewall rules allow inbound requests on this port from the IP addresses you get from the instance.
      Note:
      If you don't have a hostname and are connecting via the IP address, you can enter the IP address and put "localhost" in the Hostname environment variable.
    • To learn more, see Use TLS (HTTPS) to protect the Docker daemon socket.

    Steps to set up the Headless Browser for Windows

    Follow these seven steps (plus verification) to set up the Headless Browser for Windows.