Introduction

Many modern web applications use the HTML Canvas element to draw graphics, charts, signatures, games, diagrams, and image editors. Unlike normal HTML elements, objects drawn on a canvas do not exist as individual DOM elements.

Because of this, Selenium cannot directly locate or click a shape drawn inside a canvas using standard locators like find_element(). Instead, automation typically interacts with the canvas by clicking specific coordinates or by using JavaScript to inspect the application’s state.

In this tutorial, you’ll learn how to automate Canvas elements using Selenium with Python, along with practical examples, real-world scenarios, common mistakes, and best practices.

What are Canvas Elements?

The HTML Canvas element provides a drawing surface where JavaScript can render graphics.

Example:

Canvas

+----------------------------------+
|                                  |
|      Circle      Rectangle       |
|                                  |
|        Line      Triangle        |
|                                  |
+----------------------------------+

Although these shapes appear on the screen, they are not individual HTML elements.

Why is Canvas Different?

Canvas graphics are drawn as pixels rather than DOM elements.

This means Selenium cannot do something like:

driver.find_element(...)

to locate a circle or rectangle drawn inside the canvas.

Instead, Selenium interacts with the canvas itself using mouse coordinates or JavaScript.

Why Automate Canvas Elements?

Automating canvas elements helps you:

Test signature pads.
Verify drawing applications.
Test interactive charts.
Validate games.
Automate graphical user interfaces.

Example

from selenium import webdriver
from selenium.webdriver.common.action_chains import ActionChains
from selenium.webdriver.common.by import By


# Topic: 31. Modern Web Elements - Canvas Elements
# Practice site: https://www.testmuai.com/selenium-playground/
# Run: pytest -s 31_examples/test_06_canvas_elements.py
#
# Canvas drawings do not expose normal DOM elements for each shape. Interact
# with the canvas by coordinates or use JavaScript to inspect app state.


def test_click_canvas_by_coordinates:
    driver = webdriver.Chrome()

    try:
        driver.get("https://www.testmuai.com/selenium-playground/")

        driver.execute_script(
            """
            const canvas = document.createElement('canvas');
            canvas.id = 'demo-canvas';
            canvas.width = 200;
            canvas.height = 100;
            canvas.style.border = '1px solid black';
            canvas.addEventListener('click', event => {
                canvas.dataset.lastClick = `${event.offsetX},${event.offsetY}`;
            });
            document.body.appendChild(canvas);
            """
        )

        canvas = driver.find_element(By.ID, "demo-canvas")
        ActionChains(driver).move_to_element_with_offset(canvas, 30, 20).click().perform()

        assert canvas.get_attribute("data-last-click") is not None
    finally:
        driver.quit()

Understanding the Code

Import Required Libraries

from selenium import webdriver
from selenium.webdriver.common.action_chains import ActionChains
from selenium.webdriver.common.by import By

These modules are required to launch the browser, locate the canvas element, and perform mouse actions.

Create a Chrome Browser Instance

driver = webdriver.Chrome()

Starts a new Chrome browser session.

Open the Practice Website

driver.get("https://www.testmuai.com/selenium-playground/")

Navigates to the Selenium Playground website.

Create a Canvas Element

driver.execute_script(
    """
    ...
    """
)

This JavaScript creates:

A canvas element.
A visible border.
A click event listener.
A custom attribute named data-last-click.

Whenever the canvas is clicked, the click coordinates are stored in the custom attribute.

Locate the Canvas

canvas = driver.find_element(
    By.ID,
    "demo-canvas"
)

Locates the HTML canvas element.

Unlike SVG, Selenium cannot locate the graphics drawn inside the canvas—only the canvas itself.

Click Using Coordinates

ActionChains(driver)\
    .move_to_element_with_offset(
        canvas,
        30,
        20
    )\
    .click()\
    .perform()

Uses ActionChains to:

Move the mouse to the canvas.
Offset the pointer by 30 pixels horizontally and 20 pixels vertically.
Perform a click.

This simulates a real user clicking a specific position inside the canvas.

Verify the Click

assert canvas.get_attribute(
    "data-last-click"
) is not None

Verifies that clicking the canvas updated the custom attribute containing the click coordinates.

If the click was not registered, the test fails.

Close the Browser

driver.quit()

Closes the browser and ends the WebDriver session.

Practical Example

Suppose a banking application uses a signature pad built with HTML Canvas.

The automation script:

Opens the signature page.
Clicks or draws on the canvas.
Verifies that the signature is captured.

Automation Testing Example

Consider an online drawing application.

The automation script:

Opens the drawing board.
Clicks inside the canvas.
Draws a simple shape.
Verifies that drawing data is saved.

Real-World Example

Canvas elements are commonly used in:

Signature pads
Drawing applications
Online games
Image editors
Analytics dashboards
Interactive charts
Whiteboard applications

Examples include digital signatures, paint applications, graph editors, and browser-based games.

Advantages of Automating Canvas Elements

Tests graphical interfaces.
Supports drawing applications.
Verifies interactive charts.
Simulates real user interactions.
Improves automation coverage.

Common Mistakes Beginners Make

Trying to Locate Shapes Inside the Canvas

Objects drawn inside a canvas are not HTML elements.

Only the canvas itself can be located.

Ignoring Mouse Coordinates

Canvas interactions usually depend on coordinates rather than DOM locators.

Using Normal Clicks Without Positioning

Many canvas applications require clicks at precise coordinates.

Use ActionChains with offsets when needed.

Forgetting to Verify the Result

After interacting with the canvas, always verify the application’s state using attributes, JavaScript, or other validation mechanisms.

Best Practices

Locate the canvas element itself.
Use ActionChains for coordinate-based interactions.
Verify application state after each action.
Use JavaScript when application state is not directly visible.
Keep coordinate values maintainable and well documented.

Conclusion

Canvas elements are widely used in modern web applications for drawing graphics, signatures, games, and interactive visualizations. Because canvas graphics are rendered as pixels instead of DOM elements, Selenium interacts with the canvas using mouse coordinates rather than standard locators. Understanding canvas automation is essential for testing graphical user interfaces effectively.

Frequently Asked Questions (FAQs)

What is an HTML Canvas?

Canvas is an HTML element that provides a drawing surface for rendering graphics using JavaScript.

Why can’t Selenium locate shapes inside a canvas?

Because shapes drawn on a canvas are rendered as pixels and do not exist as separate DOM elements.

How does Selenium interact with a canvas?

Selenium typically interacts with the canvas using mouse coordinates through ActionChains or by using JavaScript to inspect application state.

When should I use `ActionChains` with a canvas?

Use ActionChains whenever the automation requires clicking, dragging, or drawing at specific positions inside the canvas.

Where are canvas elements commonly used?

Canvas elements are commonly used in signature pads, drawing applications, games, charts, whiteboards, dashboards, and image editors.

Key Takeaways

Canvas is a pixel-based drawing surface.
Graphics inside a canvas are not DOM elements.
Selenium interacts with the canvas using coordinates.
ActionChains is commonly used for canvas automation.
JavaScript can help verify application state after canvas interactions.
Canvas automation is an important Selenium skill for testing graphical web applications.