Final readme

README.md

@@ -1,4 +1,4 @@
-# yourls-ui
+# yourls-ui 1.0
 
 Small Qt tray utility for shortening URLs using the **YOURLS API**.
 
@@ -8,16 +8,20 @@ It was designed as a lightweight helper for everyday use with a self-hosted YOUR
 
 ---
 
-# Features (v0.1)
+# Features (v1.0)
 
 - System tray application
 - Simple configuration window
 - Uses YOURLS API with **signature authentication**
 - Reads URL from clipboard
+- Accepts plain URLs, quoted URLs, Markdown links and browser URL MIME data
 - Generates a short URL
+- Reuses existing short links returned by YOURLS for duplicate URLs
 - Copies the short URL back to clipboard
+- Supports Wayland clipboard access through focused dialogs and verifies copying
 - Shows popup with clickable link
 - Error reporting with API response
+- Debug-only diagnostics for clipboard and API troubleshooting
 
 ---
 
@@ -39,8 +43,8 @@ The application will:
 2. Check if the content is a valid URL
 3. Call the YOURLS API
 4. Receive a shortened link
-5. Copy the shortened link back to clipboard
-6. Show a popup window with the result
+5. Show a popup window with the result
+6. Copy the shortened link back to clipboard and verify the copy
 
 If YOURLS returns HTTP 400 with `error:url` and an existing short link for
 the same source URL, the application uses that link as a successful result.
@@ -94,6 +98,7 @@ Right click the tray icon to access the menu:
 
 ```
 Cut URL
+Settings
 Help
 About
 Exit
@@ -120,7 +125,7 @@ Build:
 ```bash
 mkdir -p build-qt6
 cd build-qt6
-qmake6 ../yourls-ui.pro
+qmake6 ../yourls-ui.pro CONFIG+=release CONFIG-=debug
 make
 ```
 
@@ -171,12 +176,77 @@ mainwindow.ui
 yourlsclient.h / yourlsclient.cpp
     YOURLS API client
     Handles HTTP requests and responses
+
+clipboardurl.h
+    Clipboard MIME data and URL text parsing
+
+clipboardresultdialog.h
+    Focus-aware clipboard writing and copy verification
+
+tests/
+    Standalone qmake projects for automated tests
 ```
 
 The YOURLS API communication is encapsulated in `YourlsClient`.
 
 ---
 
+# Tests
+
+The `tests/` directory contains three independent test executables:
+
+| Test | Coverage |
+| --- | --- |
+| `clipboardurl_test` | Plain, quoted and Markdown URLs; browser MIME URLs; query strings, fragments and parentheses; invalid or empty input. |
+| `yourlsclient_test` | HTTP 200 success, HTTP 400 duplicate reuse, rejection of mismatched or invalid links, other API errors and HTTP 500; URL encoding in requests. |
+| `clipboardresultdialog_test` | No clipboard overwrite before focus, automatic copying on activation, copy verification and retry, and copying on platforms without the focus requirement. |
+
+Tests require Qt 6 and a C++17 compiler. The API and dialog tests also require
+the **Qt Test** module; the dialog test uses Qt Widgets and the API test uses
+Qt Network.
+
+Run the following from the repository root. Each subshell builds and runs one
+test in its own directory:
+
+```bash
+mkdir -p build/tests/clipboardurl build/tests/yourlsclient build/tests/clipboardresultdialog
+
+(
+  cd build/tests/clipboardurl &&
+  qmake6 ../../../tests/clipboardurl_test.pro &&
+  make &&
+  ./clipboardurl_test
+)
+
+(
+  cd build/tests/yourlsclient &&
+  qmake6 ../../../tests/yourlsclient_test.pro &&
+  make &&
+  ./yourlsclient_test
+)
+
+(
+  cd build/tests/clipboardresultdialog &&
+  qmake6 ../../../tests/clipboardresultdialog_test.pro &&
+  make &&
+  QT_QPA_PLATFORM=offscreen ./clipboardresultdialog_test
+)
+```
+
+The API test starts a local HTTP server and requires permission to bind a
+loopback port. It uses a test signature and does not contact a real YOURLS
+instance. The dialog test uses Qt's `offscreen` platform for automated checks;
+it does not verify a real Wayland compositor.
+
+For a manual Wayland check, copy a URL in another application, choose `Cut URL`,
+activate the clipboard dialog, then activate the result window. Confirm that
+it reports a successful copy, close it with `OK`, and paste into another
+application. Repeat with the same URL to verify reuse of the existing short
+link. Debug builds additionally report `verified: true` for a successful
+clipboard write.
+
+---
+
 # API call
 
 The application performs a request similar to:
@@ -192,7 +262,7 @@ GET /yourls-api.php
 Example:
 
 ```
-https://example.com/yourls-api.php?action=shorturl&format=json&signature=ABC123&url=https://example.com
+https://example.com/yourls-api.php?action=shorturl&format=json&signature=ABC123&url=https%3A%2F%2Fexample.com
 ```
 
 ---
@@ -232,10 +302,11 @@ AppImage
 # Version
 
 ```
-v0.1
+v1.0
 ```
 
-Initial working release.
+Stable release with Wayland clipboard support, verified short URL copying,
+reuse of existing YOURLS links, automated regression tests and debug diagnostics.
 
 ---