basalt-gtk 0.0.0-rc5

package/native/tests/test_focus.cpp

@@ -0,0 +1,194 @@
+// Keyboard focus: what Tab stops on, in what order, and what Enter does.
+//
+// The manager is built standalone against a real GtkMountingManager and a real
+// window, because focus is the one part of input that needs both: GTK will not
+// give focus to a widget that is not mapped, and the chain this exercises is
+// GTK's own rather than this project's.
+//
+// No emitter is attached to these hand-built shadow views, so the focus and
+// blur events have nowhere to go and the click dispatch does nothing. What is
+// observable is the part that decides where focus actually is, which is the
+// part this project can get wrong on its own.
+
+#include "TestHarness.h"
+
+#include "GtkFocus.h"
+#include "GtkMountingManager.h"
+
+#include <react/renderer/components/view/ViewProps.h>
+
+#include <cstdint>
+#include <sstream>
+
+using facebook::react::LayoutMetrics;
+using facebook::react::MountingTransaction;
+using facebook::react::ShadowView;
+using facebook::react::ShadowViewMutation;
+using facebook::react::ShadowViewMutationList;
+using facebook::react::SurfaceId;
+using facebook::react::Tag;
+using facebook::react::TransactionTelemetry;
+using facebook::react::ViewProps;
+
+namespace {
+
+constexpr SurfaceId kSurfaceId = 1;
+
+ShadowView makeView(Tag tag, float y, bool accessible) {
+  auto props = std::make_shared<ViewProps>();
+  props->accessible = accessible;
+
+  LayoutMetrics metrics;
+  metrics.frame = {.origin = {.x = 0, .y = y}, .size = {.width = 200, .height = 40}};
+
+  ShadowView view;
+  view.componentName = "View";
+  view.surfaceId = kSurfaceId;
+  view.tag = tag;
+  view.props = props;
+  view.layoutMetrics = metrics;
+  return view;
+}
+
+// A window with a focus manager, in the order the host builds them: the manager
+// exists before the window is shown, and the first transaction arrives after.
+//
+// The order matters and is not incidental. GTK gives focus to the first
+// focusable widget when a window is shown, so a tree mounted *before* that
+// would open with something already focused -- which the AppKit host does not
+// do, and which would make an app see onFocus at startup on one desktop only.
+// The real host shows an empty window and mounts into it, and so does this.
+struct Scene {
+  basalt::GtkMountingManager manager;
+  RnView *root;
+  GtkWidget *window;
+  basalt::GtkFocusManager focus;
+
+  Scene()
+      : root(manager.createSurfaceRoot(kSurfaceId)),
+        window(gtk_window_new()),
+        focus(&manager, root) {
+
+    gtk_window_set_default_size(GTK_WINDOW(window), 400, 400);
+    gtk_window_set_child(GTK_WINDOW(window), GTK_WIDGET(root));
+    gtk_widget_set_visible(window, TRUE);
+    pump();
+  }
+
+  ~Scene() {
+    gtk_window_destroy(GTK_WINDOW(window));
+    manager.destroySurfaceRoot(kSurfaceId);
+  }
+
+  Scene(const Scene &) = delete;
+  Scene &operator=(const Scene &) = delete;
+
+  void mount(std::initializer_list<ShadowView> views) {
+    ShadowViewMutationList mutations;
+    int index = 0;
+    for (const ShadowView &view : views) {
+      mutations.push_back(ShadowViewMutation::CreateMutation(view));
+      mutations.push_back(ShadowViewMutation::InsertMutation(kSurfaceId, view, index++));
+    }
+    manager.applyTransaction(
+        kSurfaceId, MountingTransaction(kSurfaceId, 1, std::move(mutations), TransactionTelemetry{}));
+    // GTK will not give focus to a widget that is not mapped, and mapping
+    // happens in the frame clock's layout phase rather than when a child is
+    // added.
+    pump();
+  }
+
+  static void pump() {
+    const gint64 deadline = g_get_monotonic_time() + 500000; // 500ms
+    while (g_get_monotonic_time() < deadline) {
+      while (g_main_context_iteration(nullptr, FALSE)) {
+      }
+      g_usleep(1000);
+    }
+  }
+};
+
+} // namespace
+
+TEST(focus_accessible_views_are_the_ones_tab_stops_on) {
+  Scene scene;
+  // React Native's `focusable` prop never reaches this platform, so `accessible`
+  // is the signal -- and it is what <Pressable> sets on everything it renders.
+  scene.mount({makeView(10, 0, true), makeView(11, 50, false), makeView(12, 100, true)});
+
+  EXPECT(rn_view_get_focusable(scene.manager.viewForTag(10)));
+  EXPECT(!rn_view_get_focusable(scene.manager.viewForTag(11)));
+  EXPECT(rn_view_get_focusable(scene.manager.viewForTag(12)));
+  // And it shows up in the tree dump, so the cross-host diff can say the prop
+  // arrived on all three.
+  char *tree = rn_view_describe_tree(scene.root);
+  const std::string dump(tree);
+  g_free(tree);
+  EXPECT(dump.find("focusable") != std::string::npos);
+}
+
+TEST(focus_tab_visits_focusable_views_in_tree_order) {
+  Scene scene;
+  scene.mount({makeView(10, 0, true), makeView(11, 50, false), makeView(12, 100, true)});
+  // Nothing is focused when a window opens, on either desktop.
+  EXPECT_EQ((long)scene.focus.focusedTag(), 0L);
+
+  EXPECT(scene.focus.moveFocus(true));
+  EXPECT_EQ((long)scene.focus.focusedTag(), 10L);
+  // 11 is not accessible, so Tab goes past it.
+  EXPECT(scene.focus.moveFocus(true));
+  EXPECT_EQ((long)scene.focus.focusedTag(), 12L);
+}
+
+TEST(focus_tab_wraps_at_the_end) {
+  Scene scene;
+  scene.mount({makeView(10, 0, true), makeView(11, 50, true)});
+  scene.focus.moveFocus(true);
+  scene.focus.moveFocus(true);
+  EXPECT_EQ((long)scene.focus.focusedTag(), 11L);
+  // GTK's own `gtk_widget_child_focus` stops at the last child, because a real
+  // window would carry on into whatever is next -- and here the surface root
+  // *is* the content. The AppKit side wraps, so this one has to as well.
+  EXPECT(scene.focus.moveFocus(true));
+  EXPECT_EQ((long)scene.focus.focusedTag(), 10L);
+}
+
+TEST(focus_shift_tab_goes_back) {
+  Scene scene;
+  scene.mount({makeView(10, 0, true), makeView(11, 50, true)});
+  scene.focus.moveFocus(true);
+  scene.focus.moveFocus(true);
+  EXPECT_EQ((long)scene.focus.focusedTag(), 11L);
+  EXPECT(scene.focus.moveFocus(false));
+  EXPECT_EQ((long)scene.focus.focusedTag(), 10L);
+}
+
+TEST(focus_activating_nothing_is_not_a_click) {
+  Scene scene;
+  scene.mount({makeView(10, 0, true)});
+  // Nothing has focus yet, so there is nothing to activate -- and reporting a
+  // press with no target is how a keystroke reaches the wrong view.
+  EXPECT(!scene.focus.activateFocused());
+
+  scene.focus.moveFocus(true);
+  // No emitter is attached to these hand-built shadow views, so the click has
+  // nowhere to deliver. It must not crash: that is exactly the shape of Enter
+  // arriving between a Remove and its Delete.
+  EXPECT(scene.focus.activateFocused());
+}
+
+TEST(focus_a_view_that_stops_being_accessible_leaves_the_tab_order) {
+  Scene scene;
+  scene.mount({makeView(10, 0, true), makeView(11, 50, true)});
+
+  ShadowViewMutationList updates;
+  updates.push_back(
+      ShadowViewMutation::UpdateMutation(makeView(10, 0, true), makeView(10, 0, false), kSurfaceId));
+  scene.manager.applyTransaction(
+      kSurfaceId, MountingTransaction(kSurfaceId, 2, std::move(updates), TransactionTelemetry{}));
+
+  EXPECT(!rn_view_get_focusable(scene.manager.viewForTag(10)));
+  scene.focus.moveFocus(true);
+  // Tab now goes straight to 11, because 10 has left the chain.
+  EXPECT_EQ((long)scene.focus.focusedTag(), 11L);
+}

package/native/tests/test_hittest.cpp

@@ -0,0 +1,242 @@
+// Tests for hit testing.
+//
+// This is the part of input most likely to be quietly wrong, and it is a pure
+// function of the widget tree, so it can be tested without a gesture, a
+// display server, or permission to synthesise a pointer event. That matters:
+// synthesising a real click needs accessibility permission an automated run
+// does not have, so everything below GDK is tested here instead.
+
+#include "TestHarness.h"
+
+#include "GtkMountingManager.h"
+#include "GtkTouchDispatcher.h"
+#include "RnView.h"
+
+#include <sstream>
+
+namespace {
+
+RnView *addChild(RnView *parent, int tag, float x, float y, float width, float height) {
+  RnView *child = rn_view_new(tag);
+  g_object_ref_sink(child);
+  rn_view_set_frame(child, x, y, width, height);
+  rn_view_insert_child(parent, child, 0);
+  return child;
+}
+
+// gtk_widget_pick skips widgets that are not mapped, and a widget is only
+// mapped inside a window that has been shown. So these tests put the tree in a
+// real window rather than allocating it in isolation the way the layout tests
+// do -- which is also closer to what happens when a pointer actually arrives.
+//
+// Allocation happens in the frame clock's layout phase, not synchronously when
+// a child is added, so every structural change is followed by a pump that
+// spins the main loop until a frame has actually gone through. Draining the
+// context without waiting is not enough: with no frame due, the iteration
+// returns immediately and the child is still unallocated.
+struct Scene {
+  GtkWidget *window;
+  RnView *root;
+
+  explicit Scene(int width, int height) {
+    root = rn_view_new(1);
+    window = gtk_window_new();
+    gtk_window_set_default_size(GTK_WINDOW(window), width, height);
+    gtk_window_set_child(GTK_WINDOW(window), GTK_WIDGET(root));
+  }
+
+  ~Scene() { gtk_window_destroy(GTK_WINDOW(window)); }
+
+  Scene(const Scene &) = delete;
+  Scene &operator=(const Scene &) = delete;
+
+  // Call once the tree is built.
+  void show() {
+    gtk_widget_set_visible(window, TRUE);
+    pump();
+  }
+
+  // Spins the main loop for long enough that a frame is drawn and the tree is
+  // allocated. Bounded, so a machine that never produces a frame fails the
+  // assertion rather than hanging the suite.
+  static void pump() {
+    const gint64 deadline = g_get_monotonic_time() + 500000; // 500ms
+    while (g_get_monotonic_time() < deadline) {
+      while (g_main_context_iteration(nullptr, FALSE)) {
+      }
+      g_usleep(1000);
+    }
+  }
+};
+
+} // namespace
+
+TEST(hit_test_finds_the_view_under_a_point) {
+  Scene scene(400, 400);
+  addChild(scene.root, 20, 10.0F, 10.0F, 100.0F, 100.0F);
+  scene.show();
+
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 50.0, 50.0)), 20);
+}
+
+TEST(hit_test_misses_return_the_root_not_a_child) {
+  Scene scene(400, 400);
+  addChild(scene.root, 21, 10.0F, 10.0F, 50.0F, 50.0F);
+  scene.show();
+
+  // Outside the child but inside the root.
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 300.0, 300.0)), 1);
+}
+
+TEST(hit_test_returns_the_deepest_view) {
+  Scene scene(400, 400);
+  RnView *outer = addChild(scene.root, 30, 0.0F, 0.0F, 200.0F, 200.0F);
+  addChild(outer, 31, 20.0F, 20.0F, 60.0F, 60.0F);
+  scene.show();
+
+  // Inside the inner view: the inner one wins.
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 50.0, 50.0)), 31);
+  // Inside the outer view but outside the inner one.
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 150.0, 150.0)), 30);
+}
+
+TEST(hit_test_respects_sibling_order) {
+  Scene scene(400, 400);
+
+  // Two overlapping siblings. GTK paints in child order, so the later one is on
+  // top and should win a hit in the overlap.
+  addChild(scene.root, 40, 0.0F, 0.0F, 100.0F, 100.0F);
+  RnView *second = rn_view_new(41);
+  g_object_ref_sink(second);
+  rn_view_set_frame(second, 50.0F, 50.0F, 100.0F, 100.0F);
+  rn_view_insert_child(scene.root, second, 1);
+  scene.show();
+
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 25.0, 25.0)), 40);
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 125.0, 125.0)), 41);
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 75.0, 75.0)), 41);
+}
+
+TEST(hit_test_follows_a_scroll_offset) {
+  // The reason scrolling is expressed as an offset applied during allocation
+  // rather than as a paint-time translation: children really do move, so GTK's
+  // own picking follows them and hit testing needs no special case.
+  Scene scene(400, 400);
+  RnView *scroller = addChild(scene.root, 50, 0.0F, 0.0F, 200.0F, 200.0F);
+  addChild(scroller, 51, 0.0F, 300.0F, 200.0F, 100.0F);
+  scene.show();
+
+  // The row sits below the viewport, so nothing of it is under this point.
+  EXPECT(basalt::hitTestTag(scene.root, 100.0, 50.0) != 51);
+
+  rn_view_set_scroll_offset(scroller, 0.0, 300.0);
+  Scene::pump();
+
+  // Scrolled into view, the same point now lands on it.
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 100.0, 50.0)), 51);
+}
+
+TEST(hit_test_on_a_null_root_is_a_miss) {
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(nullptr, 0.0, 0.0)), 0);
+}
+
+// Hover walks the same widget tree from the same pick, and has to survive
+// everything the touch path does: a point that hits nothing, a view with no
+// emitter, and the cursor leaving the surface. No emitter is attached to
+// anything here, so nothing is delivered -- which is also what a cursor moving
+// during a surface teardown looks like from inside the dispatcher.
+TEST(a_synthesised_hover_walks_the_tree_without_an_emitter) {
+  basalt::GtkMountingManager manager;
+  RnView *root = manager.createSurfaceRoot(1);
+
+  GtkWidget *window = gtk_window_new();
+  gtk_window_set_default_size(GTK_WINDOW(window), 400, 400);
+  gtk_window_set_child(GTK_WINDOW(window), GTK_WIDGET(root));
+  addChild(root, 30, 10.0F, 10.0F, 100.0F, 100.0F);
+  gtk_widget_set_visible(window, TRUE);
+  Scene::pump();
+
+  basalt::GtkTouchDispatcher dispatcher(&manager, root);
+  dispatcher.synthesiseHover(50.0, 50.0);
+  dispatcher.synthesiseHover(300.0, 300.0);
+  // Negative means the cursor left the surface.
+  dispatcher.synthesiseHover(-1.0, -1.0);
+
+  gtk_window_destroy(GTK_WINDOW(window));
+  manager.destroySurfaceRoot(1);
+}
+
+// `pointerEvents`, which decides what a press can land on rather than what is
+// drawn. GTK expresses exactly one of the four values -- `none`, through
+// can-target -- so these are also the tests for the resolution
+// GtkTouchDispatcher does for the other two.
+TEST(pointer_events_none_passes_a_press_through_to_what_is_behind) {
+  Scene scene(400, 400);
+  RnView *behind = addChild(scene.root, 60, 0.0F, 0.0F, 200.0F, 200.0F);
+  RnView *over = rn_view_new(61);
+  g_object_ref_sink(over);
+  rn_view_set_frame(over, 0.0F, 0.0F, 200.0F, 200.0F);
+  rn_view_insert_child(scene.root, over, 1);
+  scene.show();
+  (void)behind;
+
+  // Painted last, so it is on top and takes the press.
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 50.0, 50.0)), 61);
+
+  rn_view_set_pointer_events(over, RN_POINTER_EVENTS_NONE);
+  Scene::pump();
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 50.0, 50.0)), 60);
+}
+
+TEST(pointer_events_none_takes_the_children_with_it) {
+  Scene scene(400, 400);
+  RnView *over = addChild(scene.root, 62, 0.0F, 0.0F, 200.0F, 200.0F);
+  addChild(over, 63, 0.0F, 0.0F, 100.0F, 100.0F);
+  scene.show();
+
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 50.0, 50.0)), 63);
+  // The whole subtree leaves hit testing, not just the view the prop is on --
+  // which is GTK's own can-target semantics and the reason `none` needs no
+  // help from the dispatcher.
+  rn_view_set_pointer_events(over, RN_POINTER_EVENTS_NONE);
+  Scene::pump();
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 50.0, 50.0)), 1);
+}
+
+TEST(pointer_events_box_none_is_transparent_and_its_children_are_not) {
+  Scene scene(400, 400);
+  addChild(scene.root, 64, 0.0F, 0.0F, 300.0F, 300.0F);
+  RnView *overlay = rn_view_new(65);
+  g_object_ref_sink(overlay);
+  rn_view_set_frame(overlay, 0.0F, 0.0F, 300.0F, 300.0F);
+  rn_view_insert_child(scene.root, overlay, 1);
+  addChild(overlay, 66, 0.0F, 0.0F, 100.0F, 100.0F);
+  rn_view_set_pointer_events(overlay, RN_POINTER_EVENTS_BOX_NONE);
+  scene.show();
+
+  // Over the child: the overlay's children are still targets.
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 50.0, 50.0)), 66);
+  // Over the overlay and nothing inside it: the press belongs to the view
+  // *behind*, not to the overlay's parent. Reaching that answer is what the
+  // re-pick in pickTarget is for; returning the parent would look right until
+  // something was underneath.
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 200.0, 200.0)), 64);
+  // And the view is targetable again afterwards -- the suppression lasts for
+  // one pick, not for good.
+  EXPECT(gtk_widget_get_can_target(GTK_WIDGET(overlay)));
+}
+
+TEST(pointer_events_box_only_swallows_presses_meant_for_its_children) {
+  Scene scene(400, 400);
+  RnView *panel = addChild(scene.root, 67, 0.0F, 0.0F, 300.0F, 300.0F);
+  addChild(panel, 68, 0.0F, 0.0F, 100.0F, 100.0F);
+  scene.show();
+
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 50.0, 50.0)), 68);
+  rn_view_set_pointer_events(panel, RN_POINTER_EVENTS_BOX_ONLY);
+  Scene::pump();
+  // The press lands on the panel even though it is over the child, which is
+  // what makes a disabled panel disable everything in it.
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 50.0, 50.0)), 67);
+  EXPECT_EQ(static_cast<int>(basalt::hitTestTag(scene.root, 200.0, 200.0)), 67);
+}

package/native/tests/test_image.cpp

@@ -0,0 +1,135 @@
+// Tests for the image loader.
+//
+// A base64 data: URI keeps these self-contained: no file on disk, no network,
+// no assets directory to keep in step. The loader answers synchronously for a
+// cached URI and through the main loop otherwise, so the async cases pump the
+// loop until the callback lands.
+
+#include "TestHarness.h"
+
+#include "GtkImageLoader.h"
+
+#include <sstream>
+#include <string>
+
+namespace {
+
+// A 2x1 PNG: one red pixel, one blue. Small enough to inline, real enough to
+// decode.
+const char *kTinyPngBase64 =
+    "iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAIAAAB7QOjdAAAADUlEQVR42mP4zwAE/wEHAAH/PX2MSQAAAABJRU5ErkJggg==";
+
+std::string tinyPngUri() {
+  return std::string("data:image/png;base64,") + kTinyPngBase64;
+}
+
+// Runs the main loop until `done`, or until a generous number of iterations
+// have passed. Returns false on timeout so a hang fails rather than blocks.
+bool pumpUntil(const bool &done) {
+  for (int i = 0; i < 20000 && !done; ++i) {
+    g_main_context_iteration(nullptr, FALSE);
+    g_usleep(500);
+  }
+  return done;
+}
+
+} // namespace
+
+TEST(image_loader_decodes_a_data_uri) {
+  basalt::GtkImageLoader loader;
+
+  bool done = false;
+  GdkTexture *result = nullptr;
+  std::string error;
+
+  loader.load(tinyPngUri(), [&](GdkTexture *texture, const std::string &message) {
+    result = texture;
+    error = message;
+    done = true;
+  });
+
+  EXPECT(pumpUntil(done));
+  EXPECT(error.empty());
+  EXPECT(result != nullptr);
+  if (result != nullptr) {
+    EXPECT_EQ(gdk_texture_get_width(result), 2);
+    EXPECT_EQ(gdk_texture_get_height(result), 1);
+  }
+}
+
+TEST(image_loader_serves_a_second_request_from_cache) {
+  basalt::GtkImageLoader loader;
+
+  bool first = false;
+  GdkTexture *firstTexture = nullptr;
+  loader.load(tinyPngUri(), [&](GdkTexture *texture, const std::string &) {
+    firstTexture = texture;
+    first = true;
+  });
+  EXPECT(pumpUntil(first));
+
+  // The second call must answer without going through the main loop at all,
+  // which is what stops an <Image> restarting its load on every mutation.
+  bool secondCalledSynchronously = false;
+  GdkTexture *secondTexture = nullptr;
+  loader.load(tinyPngUri(), [&](GdkTexture *texture, const std::string &) {
+    secondTexture = texture;
+    secondCalledSynchronously = true;
+  });
+
+  EXPECT(secondCalledSynchronously);
+  EXPECT(secondTexture == firstTexture);
+}
+
+TEST(image_loader_reports_a_missing_file) {
+  basalt::GtkImageLoader loader;
+
+  bool done = false;
+  GdkTexture *result = nullptr;
+  std::string error;
+
+  loader.load("/definitely/not/a/real/image.png", [&](GdkTexture *texture, const std::string &message) {
+    result = texture;
+    error = message;
+    done = true;
+  });
+
+  EXPECT(pumpUntil(done));
+  EXPECT(result == nullptr);
+  EXPECT(!error.empty());
+}
+
+TEST(image_loader_rejects_an_empty_uri_without_touching_the_loop) {
+  basalt::GtkImageLoader loader;
+
+  bool called = false;
+  std::string error;
+  loader.load("", [&](GdkTexture *texture, const std::string &message) {
+    EXPECT(texture == nullptr);
+    error = message;
+    called = true;
+  });
+
+  EXPECT(called);
+  EXPECT(!error.empty());
+}
+
+TEST(image_loader_reports_undecodable_bytes) {
+  basalt::GtkImageLoader loader;
+
+  bool done = false;
+  GdkTexture *result = nullptr;
+  std::string error;
+
+  // Valid base64, not a valid image.
+  loader.load("data:image/png;base64,bm90YW5pbWFnZQ==",
+              [&](GdkTexture *texture, const std::string &message) {
+                result = texture;
+                error = message;
+                done = true;
+              });
+
+  EXPECT(pumpUntil(done));
+  EXPECT(result == nullptr);
+  EXPECT(!error.empty());
+}

package/native/tests/test_key_events_gtk.cpp

@@ -0,0 +1,112 @@
+// A GDK key press as a key combination.
+//
+// The same ten questions appkit/tests/test_appkit_key_events.mm asks, because the
+// answers have to agree: an app that binds "ArrowLeft" or metaKey must get the
+// same key on both desktops. Where the two hosts differ is what they start from
+// -- a keyval here, an NSEvent there -- and that is the whole reason the names
+// are constants in core rather than literals in each.
+
+#include "TestHarness.h"
+
+#include "GtkKeyEvents.h"
+
+#include <sstream>
+#include <string>
+
+namespace {
+
+std::string keyOf(guint keyval, GdkModifierType state = static_cast<GdkModifierType>(0)) {
+  const auto combination = basalt::keyCombinationFrom(keyval, state);
+  return combination.has_value() ? combination->key : std::string("(none)");
+}
+
+basalt::KeyModifiers modifiersOf(guint keyval, GdkModifierType state) {
+  const auto combination = basalt::keyCombinationFrom(keyval, state);
+  return combination.has_value() ? combination->modifiers : basalt::KeyModifiers{};
+}
+
+} // namespace
+
+TEST(gtk_keys_a_plain_letter_is_itself) {
+  EXPECT_EQ(keyOf(GDK_KEY_a), std::string("a"));
+  EXPECT(modifiersOf(GDK_KEY_a, static_cast<GdkModifierType>(0)) == basalt::KeyModifiers{});
+}
+
+TEST(gtk_keys_case_comes_from_the_keyval) {
+  // GDK gives Shift+A its own keyval, so the case is already right and nothing
+  // here has to apply a modifier to get it. AppKit needs `characters` for the
+  // same result, which is the difference between the two hosts in one line.
+  EXPECT_EQ(keyOf(GDK_KEY_A, GDK_SHIFT_MASK), std::string("A"));
+  EXPECT(modifiersOf(GDK_KEY_A, GDK_SHIFT_MASK).shift);
+}
+
+TEST(gtk_keys_super_is_meta_and_not_control) {
+  // W3C names the Windows and Command keys Meta, and Super is the key in that
+  // position here -- so an app binding metaKey presses the same physical key on
+  // all three desktops.
+  const auto modifiers = modifiersOf(GDK_KEY_z, GDK_SUPER_MASK);
+  EXPECT(modifiers.meta);
+  EXPECT(!modifiers.ctrl);
+  EXPECT_EQ(keyOf(GDK_KEY_z, GDK_SUPER_MASK), std::string("z"));
+}
+
+TEST(gtk_keys_control_is_control) {
+  const auto modifiers = modifiersOf(GDK_KEY_a, GDK_CONTROL_MASK);
+  EXPECT(modifiers.ctrl);
+  EXPECT(!modifiers.meta);
+  // And the letter, not a control character: a keyval is the key rather than
+  // what it would insert, so this comes out right without the correction the
+  // AppKit host needs.
+  EXPECT_EQ(keyOf(GDK_KEY_a, GDK_CONTROL_MASK), std::string("a"));
+}
+
+TEST(gtk_keys_the_arrows_have_browser_names) {
+  EXPECT_EQ(keyOf(GDK_KEY_Left), std::string("ArrowLeft"));
+  EXPECT_EQ(keyOf(GDK_KEY_Right), std::string("ArrowRight"));
+  EXPECT_EQ(keyOf(GDK_KEY_Up), std::string("ArrowUp"));
+  EXPECT_EQ(keyOf(GDK_KEY_Down), std::string("ArrowDown"));
+  // The keypad's arrows are the same keys to an app. A person with Num Lock off
+  // pressing the 4 key means left.
+  EXPECT_EQ(keyOf(GDK_KEY_KP_Left), std::string("ArrowLeft"));
+}
+
+TEST(gtk_keys_the_navigation_block_has_browser_names) {
+  EXPECT_EQ(keyOf(GDK_KEY_Page_Up), std::string("PageUp"));
+  EXPECT_EQ(keyOf(GDK_KEY_Home), std::string("Home"));
+  EXPECT_EQ(keyOf(GDK_KEY_End), std::string("End"));
+  // Forward delete against backspace, which is the pair most easily conflated.
+  EXPECT_EQ(keyOf(GDK_KEY_Delete), std::string("Delete"));
+  EXPECT_EQ(keyOf(GDK_KEY_BackSpace), std::string("Backspace"));
+}
+
+TEST(gtk_keys_escape_enter_tab_and_space) {
+  EXPECT_EQ(keyOf(GDK_KEY_Escape), std::string("Escape"));
+  EXPECT_EQ(keyOf(GDK_KEY_Return), std::string("Enter"));
+  EXPECT_EQ(keyOf(GDK_KEY_KP_Enter), std::string("Enter"));
+  EXPECT_EQ(keyOf(GDK_KEY_Tab), std::string("Tab"));
+  // A space is a character, named " ". gdk_keyval_to_unicode gives it directly,
+  // so this is the same answer by a different route than AppKit's.
+  EXPECT_EQ(keyOf(GDK_KEY_space), std::string(" "));
+}
+
+TEST(gtk_keys_shift_tab_is_tab_with_shift) {
+  // Its own keyval here, as back-tab is its own character on AppKit.
+  EXPECT_EQ(keyOf(GDK_KEY_ISO_Left_Tab, GDK_SHIFT_MASK), std::string("Tab"));
+  EXPECT(modifiersOf(GDK_KEY_ISO_Left_Tab, GDK_SHIFT_MASK).shift);
+}
+
+TEST(gtk_keys_a_bare_modifier_is_not_a_combination) {
+  // Pressing Control on its own arrives as a keyval with no character. Offering
+  // it as a combination would fire a shortcut on the modifier alone.
+  EXPECT_EQ(keyOf(GDK_KEY_Control_L, GDK_CONTROL_MASK), std::string("(none)"));
+  EXPECT_EQ(keyOf(GDK_KEY_Shift_L, GDK_SHIFT_MASK), std::string("(none)"));
+}
+
+TEST(gtk_keys_several_modifiers_at_once) {
+  const auto modifiers =
+      modifiersOf(GDK_KEY_z, static_cast<GdkModifierType>(GDK_SUPER_MASK | GDK_SHIFT_MASK));
+  EXPECT(modifiers.meta);
+  EXPECT(modifiers.shift);
+  EXPECT(!modifiers.alt);
+  EXPECT(!modifiers.ctrl);
+}