mesa/tests

Universal Mesa Graphics Smoke Test

Multi-architecture headless graphics stack testing for Mesa, GTK3/GTK4, and the GNOME compositor.

Overview

This test suite validates the graphics stack functionality across 4 CPU architectures:

• x86_64 (Intel/AMD)
• aarch64 (ARM 64-bit)
• ppc64le (PowerPC Little-Endian)
• s390x (IBM Z System)

The tests run entirely headless (no physical display required) using xwfb-run (Xwayland framebuffer) for testing on bare metal, VMs, or CI infrastructure.

What It Tests

Phase 1: System Information & Prerequisites

• Architecture and kernel information
• CPU, memory, and hardware details
• Required package installation verification:
  • mesa-dri-drivers
  • gtk3, gtk4
  • mutter (Wayland compositor)
  • xwayland-run (headless testing framework)
  • Mesa GL/EGL/Vulkan drivers

Phase 2: Graphics Library Initialization

• Mesa GL library loading (libGL.so.1)
• GTK3/GTK4 Python bindings import test
• Software renderer availability check (llvmpipe/swrast)

Phase 3: Headless Graphics Stack

• Wayland compositor startup (xwfb-run)
• X11/Xwayland compatibility layer
• OpenGL context creation
• Renderer detection (glxinfo)
  • Reports vendor, renderer, and GL version

Phase 4: Application Rendering Tests

• GTK3 Demo: Application startup and rendering

  • gtk3-demo --list (enumerate demos)
  • gtk3-demo --run=textscroll --autoquit (actual demo execution)

• GTK4 Demo: Application startup and rendering

  • gtk4-demo --list (enumerate demos)
  • gtk4-demo --run=textscroll --autoquit (actual demo execution)

• GTK4 Visual Verification (detects rendering bugs):

  • Renders colored shapes (red, green, blue rectangles + yellow circle)
  • Saves PNG screenshot
  • Analyzes color diversity to detect black screen bug
  • Tests both default renderer and NGL renderer

• glxgears: OpenGL performance test

  • Runs for 25 seconds
  • Verifies FPS output and GL rendering

Known Issues Detected

s390x Mesa 25.2.7-3 Black Screen Bug

Symptom: GTK4 applications display black windows with the default renderer.

Detection: The visual verification test counts unique colors in the rendered PNG. A properly rendered image has 50+ unique color values; a black screen has <10.

Workaround: Setting GSK_RENDERER=ngl forces the NGL (new GL) renderer and fixes the issue.

This test suite automatically detects this failure and tests the NGL workaround.

Architecture

universal_sanity_test/
├── main.fmf                          # TMT test definition (Testing Farm)
├── graphics-smoke-test-rhts.sh      # Main test script with RHTS reporting
├── gtk4_render_test.py              # GTK4 visual verification app
└── README.md                         # This file

Test Framework: TMT (Test Management Tool)

The main.fmf file defines:

• Plan: plan-graphics-sanity-test

  • Provisioning: local (runs on current system)
  • Preparation: Installs GNOME desktop and graphics dependencies
  • Execution: TMT test runner

• Test 1: infrastructure-test (Phases 1-3)

  • Duration: 4 minutes
  • Order: 10 (runs first)
  • Tags: CI-Tier-1, graphics, infrastructure, multiarch

• Test 2: rendering-test (Phase 4)

  • Duration: 8 minutes
  • Order: 20 (runs second)
  • Tags: CI-Tier-1, graphics, rendering, visual-verification, multiarch

RHTS Reporting

All test results are reported via tmt-report-result for integration with:

• Testing Farm
• RHEL Testing Infrastructure
• CI/CD pipelines

Each test reports one of:

• PASS: Test succeeded
• FAIL: Critical test failed
• WARN: Optional test failed (doesn't affect overall result)
• SKIP: Test was skipped (dependency not available)

Usage

Run All Tests (Recommended)

./graphics-smoke-test-rhts.sh

Run Only Infrastructure Tests (Phases 1-3)

./graphics-smoke-test-rhts.sh --phase=1-3

Run Only Rendering Tests (Phase 4)

./graphics-smoke-test-rhts.sh --phase=4

Run with TMT (Testing Farm)

tmt run --all

Run Specific TMT Test

# Infrastructure only
tmt run test --name /tests/infrastructure-test

# Rendering only
tmt run test --name /tests/rendering-test

Requirements

System Requirements

• RHEL 9+, Fedora 35+, or CentOS Stream 9+
• Supported architectures: x86_64, aarch64, ppc64le, s390x
• No physical display required (fully headless)

Required Packages

The test automatically installs these if missing:

• mesa-dri-drivers - Mesa DRI drivers (required)
• mesa-libGL, mesa-libEGL, mesa-libGLES - Mesa GL libraries
• mesa-vulkan-drivers - Mesa Vulkan support
• gtk3, gtk4 - GTK widget toolkit
• xwayland-run - Headless X server wrapper
• mutter - GNOME Wayland compositor
• gnome-session-wayland-session - Wayland session components
• mesa-demos - GL utilities (glxinfo, glxgears)
• python3-gobject - Python GTK bindings

Optional Packages

• gtk3-devel, gtk4-devel - Development tools
• glx-utils - GLX utilities
• xterm - Terminal emulator

Output

Logs Directory

All logs are saved to: /tmp/graphics-test-logs/

Key files:

• 00-master-test.log - Complete test output
• prereq_system-check.log - System information and prerequisites
• app_gtk4-render-test-default.log - GTK4 default renderer test
• gtk4_render_test_default.png - Visual verification screenshot
• gtk4_render_test_ngl.png - NGL renderer screenshot

Test Results Summary

The script outputs:

• Individual test results (PASS/FAIL/WARN/SKIP)
• OpenGL renderer information
• List of generated logs and screenshots
• Overall result: PASS or FAIL

RHTS Artifacts

The following artifacts are submitted to Testing Farm:

• Master log file
• All PNG screenshots (visual evidence)
• Failed test logs (for debugging)

Customization

Environment Variables

# Set custom log directory
LOGDIR=/var/log/graphics-test ./graphics-smoke-test-rhts.sh

# Disable verbose logging
VERBOSE=0 ./graphics-smoke-test-rhts.sh

# Force specific GTK renderer
GSK_RENDERER=ngl ./graphics-smoke-test-rhts.sh --phase=4

Manual GTK4 Render Test

# Test with default renderer
xwfb-run -w 2 -- python3 gtk4_render_test.py output.png

# Test with NGL renderer
xwfb-run -w 2 -- python3 gtk4_render_test.py output_ngl.png --renderer=ngl

# Test with other renderers
xwfb-run -w 2 -- python3 gtk4_render_test.py output_cairo.png --renderer=cairo
xwfb-run -w 2 -- python3 gtk4_render_test.py output_vulkan.png --renderer=vulkan

Exit Codes

• 0 - All critical tests passed
• 1 - One or more critical tests failed

Integration Examples

CI/CD Pipeline (.gitlab-ci.yml)

graphics-test:
  stage: test
  script:
    - cd universal_sanity_test
    - ./graphics-smoke-test-rhts.sh
  artifacts:
    when: always
    paths:
      - /tmp/graphics-test-logs/
    expire_in: 7 days
  tags:
    - multiarch

Testing Farm

plans:
  - name: graphics-smoke-test
    discover:
      how: fmf
    execute:
      how: tmt

Troubleshooting

Tests Fail to Start

Problem: Missing dependencies

Solution: The script auto-installs packages, but you can pre-install:

dnf install -y mesa-dri-drivers gtk4 mutter xwayland-run

Black Screen Detected (s390x)

Problem: GTK4 apps show black windows

Solution: This is a known Mesa bug on s390x. Use NGL renderer:

GSK_RENDERER=ngl gtk4-app

glxgears Timeout

Problem: glxgears test times out or shows no FPS

Solution: Check renderer:

xwfb-run -w 2 -- glxinfo | grep -i renderer

Ensure software renderer (llvmpipe/swrast) is available.

xwfb-run Not Found

Problem: xwayland-run package not installed

Solution:

dnf install -y xwayland-run

Development & Contributions

Test Structure

Each test uses the run_test() wrapper:

run_test "test-name" \
    "command to execute" \
    "yes|no (critical)"

Adding New Tests

1. Add test to appropriate phase function in graphics-smoke-test-rhts.sh
2. Use run_test() for automatic RHTS reporting
3. Update this README with test description

Color Coding

• Blue: Section headers
• Green: Pass
• Yellow: Warning (non-critical failure)
• Red: Fail (critical failure)

License

Testing infrastructure for Mesa and GNOME graphics stack.

Contact

• Maintainer: Peter Kopec pekopec@redhat.com
• Components Tested: mesa, gtk3, gtk4, mutter, xwayland
• Tags: CI-Tier-1, graphics, multiarch, infrastructure, rendering

See Also

• TMT Documentation
• Mesa Project
• GTK Documentation
• GNOME Mutter