--- sourceDocument: Yokohama Build or modify applications sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/yokohama/application-development Release : - yokohama ft:locale : - en-US ft:publication_title : - Yokohama Build or modify applications ft:clusterId : - cadev bundleId : - cadev workflow : - Development, Data, and Analytics --- # Headless Browser setup for Microsoft Windows # Headless Browser setup for Microsoft Windows {#ariaid-title1} * Release version: Yokohama * * Updated January 30, 2025 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read Summarize ![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) 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 manually opening a browser. This setup is available for both Linux and Microsoft Windows, with this content focusing on the Windows setup. Note that the Headless Browser is a legacy feature; ServiceNow recommends using the ATF Test Generator and Cloud Runner for a streamlined experience, although Cloud Runner is not available for on-premise instances. On-premise users must continue using the Headless Browser option. 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. Other versions require a Linux host instead. * **Required software:** Docker, Java keytool (installable via Chocolatey), and OpenSSL (installable via Chocolatey). * **Network configuration:** Two-way communication between the ServiceNow instance and the Windows server is mandatory. At least one of the server's IP address or hostname must be accessible from the instance. * **Firewall:** Allow inbound access on port 2376 (or a custom port) from ServiceNow IP ranges. ## Setup Steps The setup involves seven sequential steps plus verification: 1. **Install Docker:** Prepare Docker on the Windows server to support Headless Browser containers. 2. **Generate TLS/SSL certificates:** Secure the Docker REST API and authenticate HTTP requests. 3. **Configure Docker Server:** Set Docker to authenticate all incoming requests. 4. **Create Docker image and containers:** Pull the Headless Browser Docker image from the Public Registry and create containers. 5. **Add Docker secrets:** Store the ServiceNow user password securely in Docker Secrets for test execution authentication. 6. **Configure the ServiceNow instance:** Prepare the instance to support Headless Browser functionality. 7. **Configure ATF properties:** Set Automated Test Framework properties to enable Headless Browser usage. 8. **Verify setup:** Confirm all configurations and communications are functioning correctly to ensure the Headless Browser is operational. ## Practical Impact for ServiceNow Customers By completing this setup, customers running on-premise ServiceNow instances with Windows Server 2019 can automate UI testing without manual browser interaction, enhancing test efficiency and reliability. The process requires careful network and security configurations to enable secure Docker container operations and seamless communication with the ServiceNow instance. Customers using cloud instances are encouraged to adopt Cloud Runner instead for a simpler, modern approach. 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](https://store.servicenow.com/sn_appstore_store.do#!/store/application/db1676d7421441106f046193880e0b37) 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 {#headless-browser-procedure-windows__section_id2_wqk_jpb} 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: * Docker: [Install Docker for Headless Browser setup for Microsoft Windows](https://servicenow-prod.fluidtopics.net/Vj7AX5uGB~Dx8hHaA2_wUA "Step 1 in the Windows setup for the ServiceNow Headless Browser for Automated Test Framework: Install Docker.") * Java keytool: [Chocolatey tool for javaruntime](https://community.chocolatey.org/packages/javaruntime) * OpenSSL: [Chocolatey tool for openssl](https://community.chocolatey.org/packages/openssl) {#headless-browser-procedure-windows__ul_ec4_1vk_jpb} * 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](https://support.servicenow.com/now/en/pages/automation-store?id=ns_automation_store&catalog_sys_id=b85d23ae6f086100a5117357ea3ee4f3) 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. {#headless-browser-procedure-windows__ul_frp_mzj_nsb} 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](https://docs.docker.com/engine/security/protect-access/#:~:text=Use%20TLS%20(HTTPS)%20to%20protect,to%20a%20trusted%20CA%20certificate.). {#headless-browser-procedure-windows__ul_mts_5qk_jpb} ## Steps to set up the Headless Browser for Windows {#headless-browser-procedure-windows__section_ufq_rkj_5rb} Follow these seven steps (plus verification) to set up the Headless Browser for Windows. 1. [Install Docker for Headless Browser setup for Microsoft Windows](https://servicenow-prod.fluidtopics.net/Vj7AX5uGB~Dx8hHaA2_wUA) Step 1 in the Windows setup for the ServiceNow® Headless Browser for Automated Test Framework: Install Docker. 2. [Generate certificates for Headless Browser setup for Microsoft Windows](https://servicenow-prod.fluidtopics.net/9Hg2sDwSD~nTka6o7C4JrQ) Generate TLS/SSL certificates to secure the Docker REST API and authenticate HTTP requests. 3. [Configure Docker for Headless Browser setup in Microsoft Windows](https://servicenow-prod.fluidtopics.net/c4y36y_dqyujij4wqm1Wrg) Configure Docker Server to authenticate all requests. 4. [Create the Docker image and containers for Headless Browser setup in Microsoft Windows](https://servicenow-prod.fluidtopics.net/u953NEq4djJ5sKrS6DgdPw) Pull the Docker image from the Public Registry. 5. [Add secrets to Docker for Headless Browser setup in Microsoft Windows](https://servicenow-prod.fluidtopics.net/97gg2_cyBUG0GpE0Zgp3_w) Create a Docker secret that stores the password of the ServiceNow user who will log into the instance to execute the tests. Docker Secrets is a feature of ServiceNow® for securely storing the passwords that will be used in containers. 6. [Set up instance for Headless Browser in Microsoft Windows](https://servicenow-prod.fluidtopics.net/kr8MaOdMe6tRpUJwDLK4ZQ) Step 6 in the Microsoft Windows setup for the ServiceNow® Headless Browser for ATF: Set up your instance so it can support the Headless Browser. 7. [Configure Automated Test Framework (ATF) for Headless Browser in Microsoft Windows](https://servicenow-prod.fluidtopics.net/zZ1e~ejE2TE1JjItLEqCAQ) Step 7 in the Microsoft Windows setup for the ServiceNow® Headless Browser for ATF: Configure ATF with properties. 8. [Verify Headless Browser procedures for ATF in Microsoft Windows](https://servicenow-prod.fluidtopics.net/LX3nuK5mT3ogxXjUx67WKg) Verify that your Headless Browser setup procedures have been successful.