Add webgl conformance test (New) (#2115)

1. add file_watcher in checkbox support
2. add WebGL conformance test script
3. add test cases and test plan
4. add readme

Author: hanhsuan

checkbox-support/checkbox_support/helpers/file_watcher.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+# Copyright 2025 Canonical Ltd.
+# All rights reserved.
+#
+# Written by:
+#     Hanhsuan Lee <hanhsuan.lee@canonical.com>
+#
+# Checkbox is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 3,
+# as published by the Free Software Foundation.
+#
+# Checkbox is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Checkbox.  If not, see <http://www.gnu.org/licenses/>.
+"""
+checkbox_support.helpers.file_watcher import FileWatcher
+=============================================
+
+Utility class for watching file create/modify/delete event with inotify
+"""
+import ctypes
+import struct
+import os
+
+
+class InotifyEvent:
+    """
+    A class to store inotify system event
+    """
+
+    def __init__(self, wd: int, event_type: str, cookie: int, name: str):
+        self.wd = wd  # Watch descriptor
+        self.event_type = event_type  # modify, create, delete or unknown
+        self.cookie = (
+            cookie  # unique cookie associating related events (for rename)
+        )
+        self.name = name  # file name. might be empty string
+
+    def __str__(self):
+        return "InotifyEvent(wd={}, event_type={}, cookie={}, name={})".format(
+            self.wd, self.event_type, self.cookie, self.name
+        )
+
+
+class FileWatcher:
+    """
+    This class helps to use inotify system event to monitor file status
+    """
+
+    libc = ctypes.CDLL("libc.so.6")
+
+    # inotify constants
+    _IN_MODIFY = 0x00000002
+    _IN_CREATE = 0x00000100
+    _IN_DELETE = 0x00000200
+
+    # The Linux inotify_event struct minus the flexible name array
+    # Watch descriptor: int
+    # Mask of events: uint32_t
+    # Unique cookie associating related events (for rename): uint32_t
+    # Size of name field: uint32_t
+    # Optional null-terminated name: char
+    _EVENT_STRUCT_FORMAT = "iIII"
+    _EVENT_STRUCT_SIZE = struct.calcsize(_EVENT_STRUCT_FORMAT)
+
+    def __init__(self):
+        self.fd = self.libc.inotify_init()
+        if self.fd < 0:
+            raise SystemExit("Failed to initialize inotify")
+
+    def watch_directory(self, path: str, event: str) -> int:
+        """
+        Set the watching path and event
+
+        :param path:
+            The full path of directory
+
+        :param event:
+            c: file create event
+            m: file modify event
+            d: file delete event
+            Could combine them in any order, such as "mc", "dmc"
+        :returns:
+            Watch descriptor
+        """
+        mask = 0x00000000
+        if "m" in event:
+            mask = mask | self._IN_MODIFY
+        if "d" in event:
+            mask = mask | self._IN_DELETE
+        if "c" in event:
+            mask = mask | self._IN_CREATE
+        if mask == 0x00000000:
+            mask = self._IN_MODIFY
+        return self.libc.inotify_add_watch(self.fd, path.encode("utf-8"), mask)
+
+    def stop_watch(self, wd: int):
+        """
+        Remove the watching path and event
+
+        :param wd:
+            Watch descriptor
+        """
+        return self.libc.inotify_rm_watch(self.fd, wd)
+
+    def _mask2event(self, mask: int) -> str:
+        """
+        Convert mask to human readable message
+
+        :param mask:
+            inotify event mask
+        :returns:
+            modify, create, delete or unknown
+        """
+        event_map = {
+            self._IN_MODIFY: "modify",
+            self._IN_CREATE: "create",
+            self._IN_DELETE: "delete",
+        }
+        return event_map.get(mask, "unknown")
+
+    def read_events(self, size: int) -> list:
+        """
+        Start reading event
+
+        :param size:
+            event reading size
+        :returns:
+            parsed event information list
+        """
+        try:
+            raw_data = os.read(self.fd, 1024 if size < 0 else size)
+            event = []
+            while len(raw_data) > 0:
+                wd, mask, cookie, length = struct.unpack(
+                    self._EVENT_STRUCT_FORMAT,
+                    raw_data[: self._EVENT_STRUCT_SIZE],
+                )
+                raw_data = raw_data[self._EVENT_STRUCT_SIZE :]
+                name = (
+                    raw_data[:length].rstrip(b"\0").decode("utf-8")
+                    if length > 0
+                    else ""
+                )
+                event.append(
+                    InotifyEvent(wd, self._mask2event(mask), cookie, name)
+                )
+                raw_data = raw_data[length:]
+            return event
+        except KeyboardInterrupt:
+            self.stop_watch(self.fd)

checkbox-support/checkbox_support/helpers/tests/test_file_watcher.py

@@ -0,0 +1,149 @@
+from checkbox_support.helpers.file_watcher import FileWatcher, InotifyEvent
+from unittest.mock import MagicMock, patch
+import unittest
+
+
+class TestInotifyEvent(unittest.TestCase):
+    """
+    Test the InotifyEvent data class.
+    """
+
+    def test_inotify_event_creation(self):
+        event = InotifyEvent(
+            wd=1, event_type="modify", cookie=0, name="test_file.txt"
+        )
+        self.assertEqual(event.wd, 1)
+        self.assertEqual(event.event_type, "modify")
+        self.assertEqual(event.cookie, 0)
+        self.assertEqual(event.name, "test_file.txt")
+
+
+class TestFileWatcher(unittest.TestCase):
+    """
+    Test the FileWatcher class by mocking system-level calls.
+    """
+
+    @patch.object(FileWatcher, "libc")
+    def test_initialization_success(self, mock_libc):
+        mock_libc.inotify_init.return_value = 123
+        watcher = FileWatcher()
+        self.assertEqual(watcher.fd, 123)
+
+    @patch.object(FileWatcher, "libc")
+    def test_initialization_failure(self, mock_libc):
+        mock_libc.inotify_init.return_value = -1
+        with self.assertRaises(SystemExit) as cm:
+            FileWatcher()
+        self.assertEqual(cm.exception.code, "Failed to initialize inotify")
+
+    @patch.object(FileWatcher, "libc")
+    def test_watch_directory_with_single_event(self, mock_libc):
+        mock_libc.inotify_init.return_value = 123
+        watcher = FileWatcher()
+
+        test_path = "/tmp/test_dir"
+        mock_watch_desc = 456
+        mock_libc.inotify_add_watch.return_value = mock_watch_desc
+
+        wd = watcher.watch_directory(test_path, "m")
+        mock_libc.inotify_add_watch.assert_called_with(
+            123, test_path.encode("utf-8"), 0x00000002
+        )
+        self.assertEqual(wd, mock_watch_desc)
+
+    @patch.object(FileWatcher, "libc")
+    def test_watch_directory_with_multiple_events(self, mock_libc):
+        mock_libc.inotify_init.return_value = 123
+        watcher = FileWatcher()
+
+        test_path = "/tmp/test_dir"
+        mock_watch_desc = 789
+        mock_libc.inotify_add_watch.return_value = mock_watch_desc
+
+        wd = watcher.watch_directory(test_path, "dmc")
+        expected_mask = 0x00000200 | 0x00000002 | 0x00000100
+        mock_libc.inotify_add_watch.assert_called_with(
+            123, test_path.encode("utf-8"), expected_mask
+        )
+        self.assertEqual(wd, mock_watch_desc)
+
+    @patch.object(FileWatcher, "libc")
+    def test_stop_watch(self, mock_libc):
+        mock_libc.inotify_init.return_value = 123
+        watcher = FileWatcher()
+
+        mock_watch_desc = 1011
+        watcher.stop_watch(mock_watch_desc)
+        mock_libc.inotify_rm_watch.assert_called_with(123, mock_watch_desc)
+
+    def test_mask2event(self):
+        watcher = FileWatcher()
+        self.assertEqual(watcher._mask2event(0x00000002), "modify")
+        self.assertEqual(watcher._mask2event(0x00000100), "create")
+        self.assertEqual(watcher._mask2event(0x00000200), "delete")
+        self.assertEqual(watcher._mask2event(0x0000FFFF), "unknown")
+
+    @patch("checkbox_support.helpers.file_watcher.os.read")
+    @patch("checkbox_support.helpers.file_watcher.InotifyEvent")
+    @patch.object(FileWatcher, "libc")
+    def test_read_events_single_event(
+        self, mock_libc, mock_inotify_event, mock_os_read
+    ):
+        mock_libc.inotify_init.return_value = 123
+        watcher = FileWatcher()
+
+        mock_os_read.return_value = b"\x01\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x09\x00\x00\x00filename\x00"
+
+        mock_event_instance = MagicMock()
+        mock_inotify_event.return_value = mock_event_instance
+
+        events = watcher.read_events(1024)
+
+        mock_os_read.assert_called_with(watcher.fd, 1024)
+
+        self.assertEqual(len(events), 1)
+
+        mock_inotify_event.assert_called_with(1, "modify", 0, "filename")
+
+        self.assertEqual(events[0], mock_event_instance)
+
+    @patch("checkbox_support.helpers.file_watcher.os.read")
+    @patch("checkbox_support.helpers.file_watcher.InotifyEvent")
+    @patch.object(FileWatcher, "libc")
+    def test_read_events_multiple_events(
+        self, mock_libc, mock_inotify_event, mock_os_read
+    ):
+        # Mock multiple events in a single read
+        mock_libc.inotify_init.return_value = 123
+        watcher = FileWatcher()
+
+        # Mock data for two events
+        mock_os_read.return_value = (
+            b"\x01\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x09\x00\x00\x00file_one\x00"
+            + b"\x02\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x09\x00\x00\x00file_two\x00"
+        )
+
+        events = watcher.read_events(1024)
+
+        self.assertEqual(len(events), 2)
+        mock_inotify_event.assert_any_call(1, "modify", 0, "file_one")
+        mock_inotify_event.assert_any_call(2, "delete", 0, "file_two")
+
+    @patch(
+        "checkbox_support.helpers.file_watcher.os.read",
+        side_effect=KeyboardInterrupt,
+    )
+    @patch.object(FileWatcher, "stop_watch")
+    @patch.object(FileWatcher, "libc")
+    def test_read_events_keyboard_interrupt(
+        self, mock_libc, mock_stop_watch, mock_os_read
+    ):
+        mock_libc.inotify_init.return_value = 123
+        watcher = FileWatcher()
+
+        watcher.read_events(1024)
+        mock_stop_watch.assert_called_with(watcher.fd)
+
+
+if __name__ == "__main__":
+    unittest.main()