Debugging in the Simulator and Tableau

Important: Tableau Web Data Connector 2.0 (this version) is being deprecated at Tableau 2023.1 and eventually retired. We will still support WDC 2.0 until its last compatible version of Tableau (Tableau 2022.4) goes End of Life and is no longer supported.

For information about Tableau Web Data Connector 3.0, see the WDC 3.0 documentation.


You can use the simulator included with the WDC SDK to develop and debug your connectors more quickly. The simulator is a JavaScript application that loads connectors in a similar way to Tableau Desktop. Additionally, starting with Tableau Desktop 2019.4, you can use the Chrome DevTools and the Chromium debugger to debug issues that appear in Tableau Desktop, but not in the simulator. A WDC is a web page that runs in a Chromium-based browser inside of Tableau Desktop. In versions of Tableau Desktop prior to 2019.4, you can use a built-in—although, not supported—debugger that you can use to debug WDC issues that appear in those versions of Tableau Desktop.

Use the simulator when you are developing your connector, to set breakpoints in the browser, view network requests, and more. Use Tableau Desktop periodically during development to confirm that your connector works the same as in the simulator, and then to perform your final testing.

This page includes information about developing and debugging your connectors both in the simulator and in Tableau.

Debugging in the simulator

To set up and run the simulator, follow the instructions in the Get Started section.

When you run a connector in the simulator, only the getSchema and getData parts of your connector code run in the simulator window. The interactive phase and authentication phases run in a separate window. This means that messages that you print with console.log will appear in different browser consoles.

To print messages from both windows to the console for the main simulator window, use tableau.log. For example, you might enter the following in your code:

tableau.log("My console message goes here!");

"The simulator user interface."

Simulator tips

Note: Tableau 2019.4 (and later) embeds the Qt WebEngine browser into the product to display your connector pages. Qt WebEngine is a Chromium-based browser that provides support for HTML5 and other modern features, including the ability to use the Chromium and Chrome DevTools for debugging.

Tableau Desktop 2019.3 (and earlier) embeds the Qt Webkit browser. This browser might lack some of the features of modern browsers, including specific HTML5 features. For more information on browser support, see the features in Qt 5.7, which is the version used by Tableau (10.3 to 2019.3). You might also want to see the Qt Webkit documentation on HTML5 support and the Qt Webkit HTML5 Score .

Caching in the simulator

If changes to your connector do not appear to take effect in the simulator, the browser might be caching a previous version of your connector. Here are some ways to work around caching issues:

General browser debugging tips


Debugging a WDC in Tableau Desktop 2019.4 (and later)

Starting with Tableau 2019.4, you can use the Chromium browser and the Chrome DevTools to debug your WDC while it is running in Tableau Desktop. This means you can use the Chromium browser, instead of the unsupported “Beta” debugger that was built into Tableau Desktop.

Download the Chromium Browser

To debug your WDC, you’ll need to use a Chromium-based browser (Chromium is the open-source version of Chrome). In some cases you could use Chrome, but because of version incompatibilities in the debugging protocol, we recommend using specific builds of Chromium, which matches the version of the browser running inside Tableau. Just download and unzip the file and run chrome.exe (Windows) or chromium (macOS).

Tableau Desktop version Chromium version Chrome version
Prior to 2019.4 Not Available Not available
2019.4 and later Chromium version 79 or earlier (for example, 79.0.3945.0) Chrome version 79 or earlier.

Chromium downloads for debugging Tableau 2019.1 and later

Note If you are using Tableau 2019.1 or later, you can debug WDCs in Tableau Desktop using certain versions of Chrome (versions prior to 80). Currently, you can't use Chrome version 80 (or later) for debugging your WDC.

Start Tableau with remote debugging enabled (Windows)

  1. Open a command prompt.

  2. Navigate to the Tableau Desktop directory. Replace <version> with the version of Tableau you are using (for example,Tableau 2019.4).

     cd C:\Program Files\Tableau\Tableau <version>\bin\
    
  3. Start Tableau with the remote debugging option.

     tableau.exe --remote-debugging-port=9000
    

    This command enables remote debugging of your WDC for this session of Tableau.

    Note: The remote debugging port (for example, 9000) must match the port address you use with the Chrome browser for debugging. This is not the HTTP port that you are using to host your WDC.

Start Tableau with remote debugging enabled (macOS)

  1. Open a Terminal window.

  2. Start Tableau using the following command.
    Replace <version> with the version of Tableau you are using (for example,2019.4.app).

     open /Applications/Tableau\ Desktop\ <version>.app --args --remote-debugging-port=9000
    
    

    This command enables remote debugging of your WDC for this session of Tableau.

    Note: The remote debugging port (for example, 9000) must match the port address you use with Chrome for debugging. This is not the HTTP port that you are using to host your WDC.

Debugging a WDC in Tableau Desktop using Chromium

After you enable debugging in Tableau, you can start debugging your WDC with the Chrome DevTools.

  1. Connect to a web data connector. In Tableau, open a connection to the Web Data Connector. In the WDC dialog box, enter the URL of the WDC you want to debug, and press Enter. After your WDC landing page is loaded, you will want to wait before interacting with the page so you can start the Chrome debugger and set breakpoints.

  2. Start Chrome and set the URL to http://localhost:9000
    This will bring up the page selector UI. The port (for example, 9000) must match the port address you specified as the remote debugging port when you started Tableau.

  3. In the Chrome Browser, select the WDC you want to debug from this page (under Inspectable pages).

    Note that the name of the WDC is based on the title of the web page that was loaded for the WDC.

    Remote Debugging

  4. When the Chrome debugger is connected, switch to the Sources tab and set a breakpoint (or breakpoints) in your WDC source code (for example, on the getSchema and getData methods).

  5. Switch back to Tableau and interact with the WDC. The WDC will run until it hits the breakpoint.

  6. Switch back to the Chrome browser and use the developer tools to step through your source code, examine variables, and watch the Console for messages.


Debug your WDC initial startup code

If you want to debug the initial startup of your WDC, you can set an Event Listener Breakpoint to break on the first statement whenever a JavaScript file is loaded. Then you can open the WDC home page in Tableau and connect the debugger. When you load your WDC, the debugger will break on the first module.

  1. Start Tableau in debugging mode and open the Web Data Connector dialog box.

  2. Switch to the the Chrome browser and use the developer tools (localhost:9000) and select the WDC Home page.

  3. Click the Sources pane in the debugger, and then click Event Listener Breakpoints. Under Script, select Script First Statement.

  4. Go back to Tableau and enter the URL for your WDC. When the WDC loads, the debugger will break on the first module of your source code. Use the Chrome Developer Tools to step through the start up code.


Debugging a WDC in Tableau Desktop 2019.3 (and earlier)

Tableau Desktop includes a built-in debugger that you can use to test your connectors. Use the built-in debugger when you encounter differences that you cannot debug in the simulator.

Important:

To run the built-in debugger, complete the following steps:

  1. Open a command prompt.

  2. Navigate to the Tableau Desktop directory.

    cd "C:\Program Files\Tableau\Tableau <version>\bin\"
    
  3. Run Tableau Desktop with the debugging flag:

    tableau.exe -DDebugWDC
    
  4. Connect to a web data connector.

  5. Interact with your connector and start the data gathering phase.

    The built-in debugger loads.

  6. The first time that you use the debugger, click the Sources tab, select Always enable, and click Enable Debugging.

    Enable debugging on the Sources tab.

  7. Click the Show sources button to display a list of the files used in your connector.

    View source files.

  8. Select a file to open it.

  9. To set a breakpoint, click on a line number.

  10. Press F8 to continue running your connector.

    Use breakpoints to debug your connector.