feat: register cockatrice:// and cockatrice-oracle:// protocol handlers

Adds OS-level URL-scheme handlers so users can click a link in a browser, chat client, or third-party tool to launch Cockatrice straight into a server / game / Oracle update. Supported URL forms: cockatrice://joingame?hostname=H&port=P&roomid=R&gameid=G[&spectate=1] cockatrice-oracle://update[?spoilers=1] Credentials passed via URL (username/password query params) are deliberately ignored — URLs leak through shell history, browser history, EDR capture, etc. If the target server requires auth and no saved credentials match, the Connect dialog opens pre-filled with the URL's host/port so the user types their password locally. OS integration - Linux: MimeType=x-scheme-handler/cockatrice (and -oracle) added to the .desktop files; Exec=cockatrice %u passes the URL through. - Windows: NSIS installer writes HKCR\cockatrice and HKCR\cockatrice-oracle registry entries; uninstaller removes them. - macOS: per-app Info.cockatrice.plist / Info.oracle.plist declare CFBundleURLTypes; a QFileOpenEvent filter is installed on QApplication before any nested event loop so cold-start URLs aren't lost. New abstractions - Intent (libcockatrice_utility/libcockatrice/utility/intent.h): abstract base for chained async actions. Guarantees finished() fires at most once, execute() is idempotent, self-deletes via deleteLater, and startTimeoutSafetyNet() arms a configurable per-stage deadline. Concrete intents (IntentConnectToServer, IntentLogin, IntentJoinServerRoom, IntentJoinServerGame) compose the joingame flow via UrlParser. - SingleInstanceManager: async per-user local-socket primary/secondary handshake; URL forwarded from secondary to primary with QDataStream framing both ways. shared_ptr-backed resolved flag survives every lambda capture. - UrlSchemeEventFilter (new libcockatrice_utility_gui sibling library): QObject event filter that translates macOS QFileOpenEvent into a urlReceived(QString) signal. Lives in its own Gui-bearing lib so libcockatrice_utility stays Core+Network only and doesn't drag Qt::Gui into servatrice. - UrlUtils (header-only): pure URL parsing, fully unit-tested. Wiring - MainWindow::handleUrl(QString) — single entry point for any URL source. - DlgConnect::prefillNewHost(host, port) — pre-fills new-host inputs. - ServersSettings::findSavedCredsByHostPort — case-insensitive saved-creds lookup. - TabSupervisor::requestJoinRoom + roomJoinedById / roomJoinFailedById signals, TabServer::roomAlreadyJoined for the short-circuit "already in this room" path — single source of truth for duplicate-join handling. Tests - 36 new unit tests across four single-purpose targets in tests/: - url_utils_test (22 tests) — scheme matching, port/room/game validation, spectator flag, credentials ignored, case-insensitivity. - url_scheme_event_filter_test (3 tests) — QFileOpenEvent capture. - intent_test (7 tests) — self-delete, abort propagation, parent-destruction- mid-flight, finish-once gate, execute() idempotence. - single_instance_manager_test (4 tests) — per-user socket naming, becoming- primary alone, forwarding to an existing primary, single-emission of roleResolved. Build tooling (incidental) - Dockerfile.format, docker-compose.format.yml, Makefile — a docker-based runner for format.sh that mirrors CI's desktop-lint step. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-16 03:57:46 -07:00 · 2026-05-13 19:40:05 -05:00 · 2026-05-13 19:40:05 -05:00 · 371b74732e
commit 371b74732e
parent 762e742be0
54 changed files with 2147 additions and 57 deletions
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@ -6,6 +6,10 @@ add_test(NAME dummy_test COMMAND dummy_test)
 add_test(NAME expression_test COMMAND expression_test)
 add_test(NAME test_age_formatting COMMAND test_age_formatting)
 add_test(NAME password_hash_test COMMAND password_hash_test)
+add_test(NAME url_utils_test COMMAND url_utils_test)
+add_test(NAME url_scheme_event_filter_test COMMAND url_scheme_event_filter_test)
+add_test(NAME intent_test COMMAND intent_test)
+add_test(NAME single_instance_manager_test COMMAND single_instance_manager_test)

 add_test(NAME deck_hash_performance_test COMMAND deck_hash_performance_test)
 set_tests_properties(deck_hash_performance_test PROPERTIES TIMEOUT 5)
@ -17,6 +21,10 @@ add_executable(expression_test expression_test.cpp)
 add_executable(test_age_formatting test_age_formatting.cpp)
 add_executable(password_hash_test password_hash_test.cpp)
 add_executable(deck_hash_performance_test deck_hash_performance_test.cpp)
+add_executable(url_utils_test url_utils_test.cpp)
+add_executable(url_scheme_event_filter_test url_scheme_event_filter_test.cpp)
+add_executable(intent_test intent_test.cpp)
+add_executable(single_instance_manager_test single_instance_manager_test.cpp)

 find_package(GTest)

@ -48,6 +56,10 @@ if(NOT GTEST_FOUND)
  add_dependencies(test_age_formatting gtest)
  add_dependencies(password_hash_test gtest)
  add_dependencies(deck_hash_performance_test gtest)
+  add_dependencies(url_utils_test gtest)
+  add_dependencies(url_scheme_event_filter_test gtest)
+  add_dependencies(intent_test gtest)
+  add_dependencies(single_instance_manager_test gtest)
 endif()

 include_directories(${GTEST_INCLUDE_DIRS})
@ -61,6 +73,14 @@ target_link_libraries(
  deck_hash_performance_test libcockatrice_deck_list libcockatrice_utility Threads::Threads ${GTEST_BOTH_LIBRARIES}
  ${TEST_QT_MODULES}
 )
+target_link_libraries(url_utils_test libcockatrice_utility Threads::Threads ${GTEST_BOTH_LIBRARIES} ${TEST_QT_MODULES})
+target_link_libraries(
+  url_scheme_event_filter_test libcockatrice_utility_gui Threads::Threads ${GTEST_BOTH_LIBRARIES} ${TEST_QT_MODULES}
+)
+target_link_libraries(intent_test libcockatrice_utility Threads::Threads ${GTEST_BOTH_LIBRARIES} ${TEST_QT_MODULES})
+target_link_libraries(
+  single_instance_manager_test libcockatrice_utility Threads::Threads ${GTEST_BOTH_LIBRARIES} ${TEST_QT_MODULES}
+)

 add_subdirectory(card_zone_algorithms)
 add_subdirectory(carddatabase)
--- a/tests/intent_test.cpp
+++ b/tests/intent_test.cpp
@ -0,0 +1,186 @@
+#include "gtest/gtest.h"
+#include <QCoreApplication>
+#include <QPointer>
+#include <libcockatrice/utility/intent.h>
+
+// StubIntent and PendingIntent live at file scope (not in an anonymous
+// namespace) so moc handles them straightforwardly across all supported Qt
+// versions.
+
+class StubIntent : public Intent
+{
+    Q_OBJECT
+public:
+    explicit StubIntent(QObject *parent = nullptr) : Intent(parent)
+    {
+    }
+    bool executed{false};
+
+protected:
+    void doExecute() override
+    {
+        executed = true;
+        emitFinished(true);
+    }
+};
+
+class PendingIntent : public Intent
+{
+    Q_OBJECT
+public:
+    explicit PendingIntent(QObject *parent = nullptr) : Intent(parent)
+    {
+    }
+
+protected:
+    void doExecute() override
+    {
+        // intentionally never emits finished()
+    }
+};
+
+// Emits finished(true) then finished(false) back-to-back to exercise the
+// finish-once guard.
+class DoubleEmitIntent : public Intent
+{
+    Q_OBJECT
+public:
+    explicit DoubleEmitIntent(QObject *parent = nullptr) : Intent(parent)
+    {
+    }
+
+protected:
+    void doExecute() override
+    {
+        emitFinished(true);
+        emitFinished(false); // must be a no-op
+    }
+};
+
+TEST(IntentTest, SelfDeletesAfterFinished)
+{
+    QPointer<StubIntent> weak = new StubIntent;
+    ASSERT_FALSE(weak.isNull());
+
+    weak->execute();
+    ASSERT_TRUE(weak->executed) << "doExecute() must be called synchronously by execute()";
+
+    QCoreApplication::sendPostedEvents(nullptr, QEvent::DeferredDelete);
+    ASSERT_TRUE(weak.isNull()) << "Intent must delete itself after finished() fires";
+}
+
+TEST(IntentTest, DoesNotDeleteBeforeFinished)
+{
+    QPointer<PendingIntent> weak = new PendingIntent;
+    weak->execute();
+
+    QCoreApplication::sendPostedEvents(nullptr, QEvent::DeferredDelete);
+    ASSERT_FALSE(weak.isNull()) << "Intent must stay alive while in-flight";
+
+    // Clean up manually for test hygiene.
+    delete weak.data();
+}
+
+TEST(IntentTest, AbortDeletesIntent)
+{
+    // abort() emits finished(false) without execute() being called.  The
+    // self-delete connection is wired in the constructor, so the intent
+    // should clean itself up regardless.
+    QPointer<PendingIntent> weak = new PendingIntent;
+    ASSERT_FALSE(weak.isNull());
+
+    weak->abort();
+    QCoreApplication::sendPostedEvents(nullptr, QEvent::DeferredDelete);
+    ASSERT_TRUE(weak.isNull()) << "Aborted intent must self-delete";
+}
+
+TEST(IntentTest, AbortChainPropagates)
+{
+    // Build a tiny two-stage chain: head fails, mid should abort and be
+    // deleted along with head.  Mirrors the failure-propagation pattern in
+    // UrlParser without depending on cockatrice GUI types.
+    QPointer<PendingIntent> head = new PendingIntent;
+    QPointer<PendingIntent> mid = new PendingIntent;
+
+    QObject::connect(head.data(), &Intent::finished, mid.data(), [m = mid.data()](bool ok) {
+        if (ok)
+            m->execute();
+        else
+            m->abort();
+    });
+
+    head->abort();
+
+    QCoreApplication::sendPostedEvents(nullptr, QEvent::DeferredDelete);
+    ASSERT_TRUE(head.isNull()) << "Head intent must self-delete after abort";
+    ASSERT_TRUE(mid.isNull()) << "Mid intent must self-delete after chained abort";
+}
+
+TEST(IntentTest, DeletedByParentBeforeFinished)
+{
+    // Simulates the "user closes Cockatrice mid-flow" path: an intent that
+    // never reaches finished() must die cleanly when its QObject parent
+    // (typically MainWindow) is destroyed, with no signal emission, no
+    // crash, and no leaked timer.
+    auto *parent = new QObject;
+    QPointer<PendingIntent> weak = new PendingIntent(parent);
+    weak->execute(); // never emits finished
+    ASSERT_FALSE(weak.isNull());
+
+    delete parent; // simulates MainWindow destruction
+    ASSERT_TRUE(weak.isNull()) << "Intent must die with its parent, even mid-flight";
+}
+
+TEST(IntentTest, FinishedEmitsAtMostOnce)
+{
+    // Regression: before the m_finished gate, a concrete intent that emitted
+    // finished() from multiple paths (success signal, disconnect, timeout)
+    // could deliver finished() twice to chain listeners.
+    auto *intent = new DoubleEmitIntent;
+    int finishedCount = 0;
+    bool firstValue = false;
+    QObject::connect(intent, &Intent::finished, [&](bool ok) {
+        if (finishedCount == 0)
+            firstValue = ok;
+        ++finishedCount;
+    });
+
+    intent->execute();
+
+    ASSERT_EQ(finishedCount, 1) << "finished() must be emitted exactly once even on duplicate emitFinished calls";
+    ASSERT_TRUE(firstValue) << "First emission wins (true)";
+
+    QCoreApplication::sendPostedEvents(nullptr, QEvent::DeferredDelete);
+}
+
+TEST(IntentTest, ExecuteIsIdempotent)
+{
+    // Regression: calling execute() twice must not re-enter doExecute().
+    class CountingIntent : public Intent
+    {
+    public:
+        int calls{0};
+
+    protected:
+        void doExecute() override
+        {
+            ++calls;
+        }
+    };
+
+    auto *intent = new CountingIntent;
+    intent->execute();
+    intent->execute();
+    intent->execute();
+    ASSERT_EQ(intent->calls, 1) << "execute() must be a no-op after the first call";
+    delete intent;
+}
+
+#include "intent_test.moc"
+
+int main(int argc, char **argv)
+{
+    QCoreApplication app(argc, argv);
+    ::testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
+}
--- a/tests/single_instance_manager_test.cpp
+++ b/tests/single_instance_manager_test.cpp
@ -0,0 +1,139 @@
+#include "gtest/gtest.h"
+#include <QCoreApplication>
+#include <QEventLoop>
+#include <QLocalServer>
+#include <QLocalSocket>
+#include <QRandomGenerator>
+#include <QTimer>
+#include <libcockatrice/utility/single_instance_manager.h>
+
+namespace
+{
+
+QString uniqueSocketName()
+{
+    return QStringLiteral("CockatriceTest-") + QString::number(QCoreApplication::applicationPid()) +
+           QStringLiteral("-") + QString::number(QRandomGenerator::global()->generate());
+}
+
+// Drive resolveStartupRole to completion and return the manager.
+// The caller owns the returned manager (parented to @p parent if given).
+SingleInstanceManager *makeResolvedPrimary(const QString &socketName, QObject *parent = nullptr)
+{
+    auto *mgr = new SingleInstanceManager(socketName, parent);
+    QEventLoop loop;
+    QObject::connect(mgr, &SingleInstanceManager::roleResolved, &loop, &QEventLoop::quit);
+    mgr->resolveStartupRole(QString());
+    QTimer::singleShot(5000, &loop, &QEventLoop::quit);
+    loop.exec();
+    return mgr;
+}
+
+} // namespace
+
+TEST(SingleInstanceManagerTest, PerUserSocketNameContainsBase)
+{
+    const QString name = SingleInstanceManager::perUserSocketName(QStringLiteral("CockatriceInstance"));
+    ASSERT_TRUE(name.startsWith(QStringLiteral("CockatriceInstance")))
+        << "perUserSocketName must preserve the base prefix; got " << qPrintable(name);
+}
+
+TEST(SingleInstanceManagerTest, ResolvesAsPrimaryWhenNoneExists)
+{
+    const QString socketName = uniqueSocketName();
+    QLocalServer::removeServer(socketName);
+
+    SingleInstanceManager mgr(socketName);
+    bool resolvedForwarded = true;
+    QEventLoop loop;
+    QObject::connect(&mgr, &SingleInstanceManager::roleResolved, [&](bool forwarded) {
+        resolvedForwarded = forwarded;
+        loop.quit();
+    });
+    mgr.resolveStartupRole(QString());
+
+    QTimer::singleShot(5000, &loop, &QEventLoop::quit);
+    loop.exec();
+
+    ASSERT_FALSE(resolvedForwarded) << "With no existing primary, we must become primary ourselves";
+}
+
+TEST(SingleInstanceManagerTest, ForwardsUrlToExistingPrimary)
+{
+    const QString socketName = uniqueSocketName();
+    QLocalServer::removeServer(socketName);
+
+    QObject parent;
+    auto *primary = makeResolvedPrimary(socketName, &parent);
+
+    int receivedCount = 0;
+    QString receivedUrl;
+    QObject::connect(primary, &SingleInstanceManager::urlReceived, [&](const QString &url) {
+        ++receivedCount;
+        receivedUrl = url;
+    });
+
+    SingleInstanceManager secondary(socketName);
+    bool secondaryForwarded = false;
+    QEventLoop loop;
+    // Wait on roleResolved (the terminal event of the handshake) rather than
+    // urlReceived: the secondary's roleResolved fires only after the ACK has
+    // round-tripped back from the primary, which itself happens after the
+    // primary emits urlReceived.  By the time we quit here, all three of
+    // secondaryForwarded / receivedCount / receivedUrl are set.
+    QObject::connect(&secondary, &SingleInstanceManager::roleResolved, [&](bool forwarded) {
+        secondaryForwarded = forwarded;
+        loop.quit();
+    });
+
+    const QString url = QStringLiteral("cockatrice://joingame?hostname=example.com&port=4748&roomid=1&gameid=42");
+    secondary.resolveStartupRole(url);
+
+    QTimer::singleShot(5000, &loop, &QEventLoop::quit);
+    loop.exec();
+
+    ASSERT_TRUE(secondaryForwarded) << "Secondary should resolve as forwarded when primary exists";
+    ASSERT_EQ(receivedCount, 1) << "urlReceived should fire exactly once on the primary";
+    ASSERT_EQ(receivedUrl, url);
+}
+
+TEST(SingleInstanceManagerTest, RoleResolvedEmitsAtMostOnce)
+{
+    // Regression: the probe-side shared flag must keep roleResolved single-
+    // emission even when multiple of QLocalSocket's signals fire (e.g.
+    // errorOccurred after a successful readyRead, or a timeout firing in the
+    // same tick as the terminal signal).  Pre-fix the flag's storage was
+    // delete-then-read on subsequent fires, UB whose only visible symptom on
+    // a forgiving allocator was duplicate emission — so we observe that.
+    const QString socketName = uniqueSocketName();
+    QLocalServer::removeServer(socketName);
+
+    QObject parent;
+    auto *primary = makeResolvedPrimary(socketName, &parent);
+    Q_UNUSED(primary);
+
+    SingleInstanceManager secondary(socketName);
+    int resolvedCount = 0;
+    QObject::connect(&secondary, &SingleInstanceManager::roleResolved, [&](bool) { ++resolvedCount; });
+
+    QEventLoop loop;
+    QObject::connect(&secondary, &SingleInstanceManager::roleResolved, &loop, &QEventLoop::quit);
+    secondary.resolveStartupRole(
+        QStringLiteral("cockatrice://joingame?hostname=example.com&port=4748&roomid=1&gameid=42"));
+
+    QTimer::singleShot(5000, &loop, &QEventLoop::quit);
+    loop.exec();
+
+    // Give any straggling signals (errorOccurred on socket teardown,
+    // timeout that may have armed) a chance to fire before we count.
+    QCoreApplication::processEvents();
+
+    ASSERT_EQ(resolvedCount, 1) << "roleResolved must fire exactly once across the entire handshake";
+}
+
+int main(int argc, char **argv)
+{
+    QCoreApplication app(argc, argv);
+    ::testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
+}
--- a/tests/url_scheme_event_filter_test.cpp
+++ b/tests/url_scheme_event_filter_test.cpp
@ -0,0 +1,63 @@
+#include "gtest/gtest.h"
+#include <QCoreApplication>
+#include <QFileOpenEvent>
+#include <QUrl>
+#include <libcockatrice/utility_gui/url_scheme_event_filter.h>
+
+TEST(UrlSchemeEventFilterTest, EmitsAndConsumesMatchingUrl)
+{
+    UrlSchemeEventFilter filter(QStringLiteral("cockatrice://"));
+
+    int callCount = 0;
+    QString received;
+    QObject::connect(&filter, &UrlSchemeEventFilter::urlReceived, [&](const QString &url) {
+        ++callCount;
+        received = url;
+    });
+
+    const QString url = QStringLiteral("cockatrice://joingame?hostname=example.com&port=4748");
+    QUrl qurl{url};
+    QFileOpenEvent event{qurl};
+    const bool consumed = filter.eventFilter(nullptr, &event);
+
+    ASSERT_TRUE(consumed) << "Matching URL should be consumed by the filter";
+    ASSERT_EQ(callCount, 1) << "urlReceived should have been emitted once";
+    ASSERT_EQ(received, url) << "Emitted URL should match the event URL";
+}
+
+TEST(UrlSchemeEventFilterTest, PassesThroughNonMatchingUrl)
+{
+    UrlSchemeEventFilter filter(QStringLiteral("cockatrice://"));
+
+    int callCount = 0;
+    QObject::connect(&filter, &UrlSchemeEventFilter::urlReceived, [&](const QString &) { ++callCount; });
+
+    QUrl qurl{QStringLiteral("https://example.com")};
+    QFileOpenEvent event{qurl};
+    const bool consumed = filter.eventFilter(nullptr, &event);
+
+    ASSERT_FALSE(consumed) << "Non-matching URL should not be consumed";
+    ASSERT_EQ(callCount, 0) << "urlReceived should not have been emitted";
+}
+
+TEST(UrlSchemeEventFilterTest, MatchesCaseInsensitively)
+{
+    UrlSchemeEventFilter filter(QStringLiteral("cockatrice://"));
+
+    int callCount = 0;
+    QObject::connect(&filter, &UrlSchemeEventFilter::urlReceived, [&](const QString &) { ++callCount; });
+
+    QUrl qurl{QStringLiteral("Cockatrice://joingame?hostname=example.com&port=4748")};
+    QFileOpenEvent event{qurl};
+    const bool consumed = filter.eventFilter(nullptr, &event);
+
+    ASSERT_TRUE(consumed);
+    ASSERT_EQ(callCount, 1);
+}
+
+int main(int argc, char **argv)
+{
+    QCoreApplication app(argc, argv);
+    ::testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
+}
--- a/tests/url_utils_test.cpp
+++ b/tests/url_utils_test.cpp
@ -0,0 +1,187 @@
+#include "gtest/gtest.h"
+#include <QCoreApplication>
+#include <libcockatrice/utility/url_utils.h>
+
+// ---------------------------------------------------------------------------
+// UrlUtils::findUrlArgument
+// ---------------------------------------------------------------------------
+
+TEST(UrlUtilsTest, FindsMatchingArgument)
+{
+    const QStringList args{QStringLiteral("--debug"),
+                           QStringLiteral("cockatrice://joingame?hostname=example.com&port=4748")};
+    ASSERT_EQ(UrlUtils::findUrlArgument(args, QStringLiteral("cockatrice://")),
+              QStringLiteral("cockatrice://joingame?hostname=example.com&port=4748"));
+}
+
+TEST(UrlUtilsTest, ReturnsEmptyStringWhenNoMatch)
+{
+    const QStringList args{QStringLiteral("--debug"), QStringLiteral("foo"), QStringLiteral("bar")};
+    ASSERT_TRUE(UrlUtils::findUrlArgument(args, QStringLiteral("cockatrice://")).isEmpty());
+}
+
+TEST(UrlUtilsTest, FindsArgumentCaseInsensitively)
+{
+    const QStringList args{QStringLiteral("Cockatrice://joingame?hostname=example.com&port=4748")};
+    ASSERT_EQ(UrlUtils::findUrlArgument(args, QStringLiteral("cockatrice://")),
+              QStringLiteral("Cockatrice://joingame?hostname=example.com&port=4748"));
+}
+
+TEST(UrlUtilsTest, ReturnsFirstMatchOnly)
+{
+    const QStringList args{QStringLiteral("cockatrice://joingame?first=1"),
+                           QStringLiteral("cockatrice://joingame?second=2")};
+    ASSERT_EQ(UrlUtils::findUrlArgument(args, QStringLiteral("cockatrice://")),
+              QStringLiteral("cockatrice://joingame?first=1"));
+}
+
+// ---------------------------------------------------------------------------
+// UrlUtils::parseOracleUrl
+// ---------------------------------------------------------------------------
+
+TEST(ParseOracleUrlTest, RecognisesUpdate)
+{
+    const auto action = UrlUtils::parseOracleUrl(QStringLiteral("cockatrice-oracle://update"));
+    ASSERT_TRUE(action.isUpdate);
+    ASSERT_FALSE(action.spoilersOnly);
+}
+
+TEST(ParseOracleUrlTest, RecognisesUpdateWithSpoilers)
+{
+    const auto action = UrlUtils::parseOracleUrl(QStringLiteral("cockatrice-oracle://update?spoilers=1"));
+    ASSERT_TRUE(action.isUpdate);
+    ASSERT_TRUE(action.spoilersOnly);
+}
+
+TEST(ParseOracleUrlTest, IgnoresUnknownHost)
+{
+    const auto action = UrlUtils::parseOracleUrl(QStringLiteral("cockatrice-oracle://unrelated"));
+    ASSERT_FALSE(action.isUpdate);
+}
+
+TEST(ParseOracleUrlTest, MatchesHostCaseInsensitively)
+{
+    const auto action = UrlUtils::parseOracleUrl(QStringLiteral("cockatrice-oracle://UPDATE"));
+    ASSERT_TRUE(action.isUpdate);
+}
+
+// ---------------------------------------------------------------------------
+// UrlUtils::parseJoinGameUrl
+// ---------------------------------------------------------------------------
+
+namespace
+{
+const QString kValidUrl = QStringLiteral("cockatrice://joingame?hostname=example.com&port=4748&roomid=1&gameid=42");
+}
+
+TEST(ParseJoinGameUrlTest, ParsesHappyPath)
+{
+    const auto parsed = UrlUtils::parseJoinGameUrl(kValidUrl);
+    ASSERT_TRUE(parsed.has_value());
+    ASSERT_EQ(parsed->hostname, QStringLiteral("example.com"));
+    ASSERT_EQ(parsed->port, 4748);
+    ASSERT_EQ(parsed->roomId, 1);
+    ASSERT_EQ(parsed->gameId, 42);
+    ASSERT_FALSE(parsed->spectator);
+}
+
+TEST(ParseJoinGameUrlTest, AcceptsSpectateFlag)
+{
+    const auto parsed = UrlUtils::parseJoinGameUrl(kValidUrl + QStringLiteral("&spectate=1"));
+    ASSERT_TRUE(parsed.has_value());
+    ASSERT_TRUE(parsed->spectator);
+}
+
+TEST(ParseJoinGameUrlTest, SpectateZeroIsNotSpectator)
+{
+    const auto parsed = UrlUtils::parseJoinGameUrl(kValidUrl + QStringLiteral("&spectate=0"));
+    ASSERT_TRUE(parsed.has_value());
+    ASSERT_FALSE(parsed->spectator);
+}
+
+TEST(ParseJoinGameUrlTest, MatchesSchemeCaseInsensitively)
+{
+    const auto parsed = UrlUtils::parseJoinGameUrl(
+        QStringLiteral("Cockatrice://joingame?hostname=example.com&port=4748&roomid=1&gameid=42"));
+    ASSERT_TRUE(parsed.has_value());
+}
+
+TEST(ParseJoinGameUrlTest, RejectsInvalidScheme)
+{
+    const auto parsed =
+        UrlUtils::parseJoinGameUrl(QStringLiteral("http://joingame?hostname=example.com&port=4748&roomid=1&gameid=42"));
+    ASSERT_FALSE(parsed.has_value());
+}
+
+TEST(ParseJoinGameUrlTest, RejectsUnsupportedHost)
+{
+    const auto parsed = UrlUtils::parseJoinGameUrl(
+        QStringLiteral("cockatrice://something?hostname=example.com&port=4748&roomid=1&gameid=42"));
+    ASSERT_FALSE(parsed.has_value());
+}
+
+TEST(ParseJoinGameUrlTest, RejectsMissingHostname)
+{
+    const auto parsed =
+        UrlUtils::parseJoinGameUrl(QStringLiteral("cockatrice://joingame?port=4748&roomid=1&gameid=42"));
+    ASSERT_FALSE(parsed.has_value());
+}
+
+TEST(ParseJoinGameUrlTest, RejectsZeroPort)
+{
+    const auto parsed = UrlUtils::parseJoinGameUrl(
+        QStringLiteral("cockatrice://joingame?hostname=example.com&port=0&roomid=1&gameid=42"));
+    ASSERT_FALSE(parsed.has_value());
+}
+
+TEST(ParseJoinGameUrlTest, RejectsOutOfRangePort)
+{
+    const auto parsed = UrlUtils::parseJoinGameUrl(
+        QStringLiteral("cockatrice://joingame?hostname=example.com&port=99999&roomid=1&gameid=42"));
+    ASSERT_FALSE(parsed.has_value());
+}
+
+TEST(ParseJoinGameUrlTest, RejectsNonNumericPort)
+{
+    const auto parsed = UrlUtils::parseJoinGameUrl(
+        QStringLiteral("cockatrice://joingame?hostname=example.com&port=abc&roomid=1&gameid=42"));
+    ASSERT_FALSE(parsed.has_value());
+}
+
+TEST(ParseJoinGameUrlTest, RejectsNegativeRoomId)
+{
+    const auto parsed = UrlUtils::parseJoinGameUrl(
+        QStringLiteral("cockatrice://joingame?hostname=example.com&port=4748&roomid=-1&gameid=42"));
+    ASSERT_FALSE(parsed.has_value());
+}
+
+TEST(ParseJoinGameUrlTest, RejectsNegativeGameId)
+{
+    const auto parsed = UrlUtils::parseJoinGameUrl(
+        QStringLiteral("cockatrice://joingame?hostname=example.com&port=4748&roomid=1&gameid=-1"));
+    ASSERT_FALSE(parsed.has_value());
+}
+
+TEST(ParseJoinGameUrlTest, IgnoresCredentialQueryParams)
+{
+    // Regression test for the security blocker: even if username/password are
+    // present in the URL (e.g. legacy bookmark), they must not surface in the
+    // parsed output.  Parsing should succeed and yield the same params as the
+    // equivalent URL without those fields.
+    const auto withCreds = UrlUtils::parseJoinGameUrl(kValidUrl + QStringLiteral("&username=alice&password=hunter2"));
+    const auto withoutCreds = UrlUtils::parseJoinGameUrl(kValidUrl);
+    ASSERT_TRUE(withCreds.has_value());
+    ASSERT_TRUE(withoutCreds.has_value());
+    ASSERT_EQ(withCreds->hostname, withoutCreds->hostname);
+    ASSERT_EQ(withCreds->port, withoutCreds->port);
+    ASSERT_EQ(withCreds->roomId, withoutCreds->roomId);
+    ASSERT_EQ(withCreds->gameId, withoutCreds->gameId);
+    ASSERT_EQ(withCreds->spectator, withoutCreds->spectator);
+}
+
+int main(int argc, char **argv)
+{
+    QCoreApplication app(argc, argv);
+    ::testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
+}