From 206a6543f64d1fc28ef112a6cde1db26aeeab964 Mon Sep 17 00:00:00 2001
From: hq1 <hq@mtod.org>
Date: Fri, 24 May 2024 16:23:25 +0200
Subject: [PATCH] First pass: extract verification errors (#4138)

* First pass: extract verification errors

We like to make them easier to maintain.
An update fixing documentation URLs will follow.

* Update moduledoc
---
 lib/plausible/verification/diagnostics.ex     | 208 ++------
 lib/plausible/verification/errors.ex          | 130 +++++
 .../site/verification/checks_test.exs         | 447 +++++-------------
 3 files changed, 293 insertions(+), 492 deletions(-)
 create mode 100644 lib/plausible/verification/errors.ex

diff --git a/lib/plausible/verification/diagnostics.ex b/lib/plausible/verification/diagnostics.ex
index 6aa44c8df3ca..907d501ff1dd 100644
--- a/lib/plausible/verification/diagnostics.ex
+++ b/lib/plausible/verification/diagnostics.ex
@@ -1,9 +1,11 @@
 defmodule Plausible.Verification.Diagnostics do
   @moduledoc """
-  Module responsible for translating diagnostics to user-friendly messages and recommendations.
+  Module responsible for translating diagnostics to user-friendly errors and recommendations.
   """
   require Logger
 
+  @errors Plausible.Verification.Errors.all()
+
   defstruct plausible_installed?: false,
             snippets_found_in_head: 0,
             snippets_found_in_body: 0,
@@ -47,14 +49,7 @@ defmodule Plausible.Verification.Diagnostics do
   end
 
   def interpret(%__MODULE__{plausible_installed?: false, gtm_likely?: true}, _url) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered an issue with your Plausible integration"],
-      recommendations: [
-        {"As you're using Google Tag Manager, you'll need to use a GTM-specific Plausible snippet",
-         "https://plausible.io/docs/google-tag-manager"}
-      ]
-    }
+    error(@errors.gtm)
   end
 
   def interpret(
@@ -66,14 +61,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered an issue with your site's CSP"],
-      recommendations: [
-        {"Please add plausible.io domain specifically to the allowed list of domains in your Content Security Policy (CSP)",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
-    }
+    error(@errors.csp)
   end
 
   def interpret(
@@ -87,13 +75,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We couldn't find the Plausible snippet on your site"],
-      recommendations: [
-        {"Please insert the snippet into your site", "https://plausible.io/docs/plausible-script"}
-      ]
-    }
+    error(@errors.no_snippet)
   end
 
   def interpret(
@@ -103,14 +85,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We couldn't reach #{url}. Is your site up?"],
-      recommendations: [
-        {"If your site is running at a different location, please manually check your integration",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
-    }
+    error(@errors.unreachable, url: url)
   end
 
   def interpret(
@@ -121,14 +96,7 @@ defmodule Plausible.Verification.Diagnostics do
         _url
       )
       when not is_nil(service_error) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered a temporary problem verifying your website"],
-      recommendations: [
-        {"Please try again in a few minutes or manually check your integration",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
-    }
+    error(@errors.temporary)
   end
 
   def interpret(
@@ -139,14 +107,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We couldn't reach #{url}. Is your site up?"],
-      recommendations: [
-        {"If your site is running at a different location, please manually check your integration",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
-    }
+    error(@errors.unreachable, url: url)
   end
 
   def interpret(
@@ -159,14 +120,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered a problem trying to verify your website"],
-      recommendations: [
-        {"The integration may be working but as you're running an older version of our script, we cannot verify it automatically. Please manually check your integration or update to use the latest script",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
-    }
+    error(@errors.old_script)
   end
 
   def interpret(
@@ -180,14 +134,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered a problem trying to verify your website"],
-      recommendations: [
-        {"The integration may be working but as you're running an older version of our script, we cannot verify it automatically. Please install our WordPress plugin to use the built-in proxy",
-         "https://plausible.io/wordpress-analytics-plugin"}
-      ]
-    }
+    error(@errors.old_script_wp_no_plugin)
   end
 
   def interpret(
@@ -201,14 +148,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered a problem trying to verify your website"],
-      recommendations: [
-        {"The integration may be working but as you're running an older version of our script, we cannot verify it automatically. Please disable and then enable the proxy in our WordPress plugin, then clear your WordPress cache",
-         "https://plausible.io/wordpress-analytics-plugin"}
-      ]
-    }
+    error(@errors.old_script_wp_plugin)
   end
 
   def interpret(
@@ -219,14 +159,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered an error with your Plausible proxy"],
-      recommendations: [
-        {"Please check whether you've configured the /event route correctly",
-         "https://plausible.io/docs/proxy/introduction"}
-      ]
-    }
+    error(@errors.proxy_misconfigured)
   end
 
   def interpret(
@@ -239,14 +172,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered an error with your Plausible proxy"],
-      recommendations: [
-        {"Please re-enable the proxy in our WordPress plugin to start counting your visitors",
-         "https://plausible.io/wordpress-analytics-plugin"}
-      ]
-    }
+    error(@errors.proxy_wp_no_plugin)
   end
 
   def interpret(
@@ -258,14 +184,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered an error with your Plausible proxy"],
-      recommendations: [
-        {"Please check your proxy configuration to make sure it's set up correctly",
-         "https://plausible.io/docs/proxy/introduction"}
-      ]
-    }
+    error(@errors.proxy_general)
   end
 
   def interpret(
@@ -273,14 +192,7 @@ defmodule Plausible.Verification.Diagnostics do
         _url
       )
       when count_head + count_body > 1 do
-    %Result{
-      ok?: false,
-      errors: ["We've found multiple Plausible snippets on your site."],
-      recommendations: [
-        {"Please ensure that only one snippet is used",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
-    }
+    error(@errors.multiple_snippets)
   end
 
   def interpret(
@@ -293,14 +205,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered an issue with your site cache"],
-      recommendations: [
-        {"Please clear your WordPress cache to ensure that the latest version of your site is being displayed to all your visitors",
-         "https://plausible.io/wordpress-analytics-plugin"}
-      ]
-    }
+    error(@errors.cache_wp_plugin)
   end
 
   def interpret(
@@ -313,14 +218,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered an issue with your site cache"],
-      recommendations: [
-        {"Please install and activate our WordPress plugin to start counting your visitors",
-         "https://plausible.io/wordpress-analytics-plugin"}
-      ]
-    }
+    error(@errors.cache_wp_no_plugin)
   end
 
   def interpret(
@@ -332,37 +230,16 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["We encountered an issue with your site cache"],
-      recommendations: [
-        {"Please clear your cache (or wait for your provider to clear it) to ensure that the latest version of your site is being displayed to all your visitors",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
-    }
+    error(@errors.cache_general)
   end
 
   def interpret(%__MODULE__{snippets_found_in_head: 0, snippets_found_in_body: n}, _url)
       when n >= 1 do
-    %Result{
-      ok?: false,
-      errors: ["Plausible snippet is placed in the body of your site"],
-      recommendations: [
-        {"Please relocate the snippet to the header of your site",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
-    }
+    error(@errors.snippet_in_body)
   end
 
   def interpret(%__MODULE__{data_domain_mismatch?: true}, "https://" <> domain) do
-    %Result{
-      ok?: false,
-      errors: ["Your data-domain is different than #{domain}"],
-      recommendations: [
-        {"Please ensure that the site in the data-domain attribute is an exact match to the site as you added it to your Plausible account",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
-    }
+    error(@errors.different_data_domain, domain: domain)
   end
 
   def interpret(
@@ -374,14 +251,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["A performance optimization plugin seems to have altered our snippet"],
-      recommendations: [
-        {"Please whitelist our script in your performance optimization plugin to stop it from changing our snippet",
-         "https://plausible.io/wordpress-analytics-plugin "}
-      ]
-    }
+    error(@errors.illegal_attrs_wp_plugin)
   end
 
   def interpret(
@@ -393,14 +263,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["A performance optimization plugin seems to have altered our snippet"],
-      recommendations: [
-        {"Please install and activate our WordPress plugin to avoid the most common plugin conflicts",
-         "https://plausible.io/wordpress-analytics-plugin "}
-      ]
-    }
+    error(@errors.illegal_attrs_wp_no_plugin)
   end
 
   def interpret(
@@ -411,14 +274,7 @@ defmodule Plausible.Verification.Diagnostics do
         },
         _url
       ) do
-    %Result{
-      ok?: false,
-      errors: ["Something seems to have altered our snippet"],
-      recommendations: [
-        {"Please manually check your integration to make sure that nothing prevents our script from working",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
-    }
+    error(@errors.illegal_attrs_general)
   end
 
   def interpret(
@@ -443,13 +299,19 @@ defmodule Plausible.Verification.Diagnostics do
       }
     )
 
+    error(@errors.unknown)
+  end
+
+  defp error(error) do
     %Result{
       ok?: false,
-      errors: ["Your Plausible integration is not working"],
-      recommendations: [
-        {"Please manually check your integration to make sure that the Plausible snippet has been inserted correctly",
-         "https://plausible.io/docs/troubleshoot-integration"}
-      ]
+      errors: [error.message],
+      recommendations: [{error.recommendation, error.url}]
     }
   end
+
+  defp error(error, assigns) do
+    message = EEx.eval_string(error.message, assigns: assigns)
+    error(%{error | message: message})
+  end
 end
diff --git a/lib/plausible/verification/errors.ex b/lib/plausible/verification/errors.ex
new file mode 100644
index 000000000000..742189a63083
--- /dev/null
+++ b/lib/plausible/verification/errors.ex
@@ -0,0 +1,130 @@
+defmodule Plausible.Verification.Errors do
+  @moduledoc """
+  A go-to definition of all verification errors
+  """
+
+  @errors %{
+    gtm: %{
+      message: "We encountered an issue with your Plausible integration",
+      recommendation:
+        "As you're using Google Tag Manager, you'll need to use a GTM-specific Plausible snippet",
+      url: "https://plausible.io/docs/google-tag-manager"
+    },
+    csp: %{
+      message: "We encountered an issue with your site's CSP",
+      recommendation:
+        "Please add plausible.io domain specifically to the allowed list of domains in your Content Security Policy (CSP)",
+      url: "https://plausible.io/docs/troubleshoot-integration"
+    },
+    unreachable: %{
+      message: "We couldn't reach <%= @url %>. Is your site up?",
+      recommendation:
+        "If your site is running at a different location, please manually check your integration",
+      url: "https://plausible.io/docs/troubleshoot-integration"
+    },
+    no_snippet: %{
+      message: "We couldn't find the Plausible snippet on your site",
+      recommendation: "Please insert the snippet into your site",
+      url: "https://plausible.io/docs/plausible-script"
+    },
+    temporary: %{
+      message: "We encountered a temporary problem verifying your website",
+      recommendation: "Please try again in a few minutes or manually check your integration",
+      url: "https://plausible.io/docs/troubleshoot-integration"
+    },
+    old_script: %{
+      message: "We encountered a problem trying to verify your website",
+      recommendation:
+        "The integration may be working but as you're running an older version of our script, we cannot verify it automatically. Please manually check your integration or update to use the latest script",
+      url: "https://plausible.io/docs/troubleshoot-integration"
+    },
+    old_script_wp_no_plugin: %{
+      message: "We encountered a problem trying to verify your website",
+      recommendation:
+        "The integration may be working but as you're running an older version of our script, we cannot verify it automatically. Please install our WordPress plugin to use the built-in proxy",
+      url: "https://plausible.io/wordpress-analytics-plugin"
+    },
+    old_script_wp_plugin: %{
+      message: "We encountered a problem trying to verify your website",
+      recommendation:
+        "The integration may be working but as you're running an older version of our script, we cannot verify it automatically. Please disable and then enable the proxy in our WordPress plugin, then clear your WordPress cache",
+      url: "https://plausible.io/wordpress-analytics-plugin"
+    },
+    proxy_misconfigured: %{
+      message: "We encountered an error with your Plausible proxy",
+      recommendation: "Please check whether you've configured the /event route correctly",
+      url: "https://plausible.io/docs/proxy/introduction"
+    },
+    proxy_wp_no_plugin: %{
+      message: "We encountered an error with your Plausible proxy",
+      recommendation:
+        "Please re-enable the proxy in our WordPress plugin to start counting your visitors",
+      url: "https://plausible.io/wordpress-analytics-plugin"
+    },
+    proxy_general: %{
+      message: "We encountered an error with your Plausible proxy",
+      recommendation: "Please check your proxy configuration to make sure it's set up correctly",
+      url: "https://plausible.io/docs/proxy/introduction"
+    },
+    multiple_snippets: %{
+      message: "We've found multiple Plausible snippets on your site.",
+      recommendation: "Please ensure that only one snippet is used",
+      url: "https://plausible.io/docs/troubleshoot-integration"
+    },
+    cache_wp_plugin: %{
+      message: "We encountered an issue with your site cache",
+      recommendation:
+        "Please clear your WordPress cache to ensure that the latest version of your site is being displayed to all your visitors",
+      url: "https://plausible.io/wordpress-analytics-plugin"
+    },
+    cache_wp_no_plugin: %{
+      message: "We encountered an issue with your site cache",
+      recommendation:
+        "Please install and activate our WordPress plugin to start counting your visitors",
+      url: "https://plausible.io/wordpress-analytics-plugin"
+    },
+    cache_general: %{
+      message: "We encountered an issue with your site cache",
+      recommendation:
+        "Please clear your cache (or wait for your provider to clear it) to ensure that the latest version of your site is being displayed to all your visitors",
+      url: "https://plausible.io/docs/troubleshoot-integration"
+    },
+    snippet_in_body: %{
+      message: "Plausible snippet is placed in the body of your site",
+      recommendation: "Please relocate the snippet to the header of your site",
+      url: "https://plausible.io/docs/troubleshoot-integration"
+    },
+    different_data_domain: %{
+      message: "Your data-domain is different than <%= @domain %>",
+      recommendation:
+        "Please ensure that the site in the data-domain attribute is an exact match to the site as you added it to your Plausible account",
+      url: "https://plausible.io/docs/troubleshoot-integration"
+    },
+    illegal_attrs_wp_plugin: %{
+      message: "A performance optimization plugin seems to have altered our snippet",
+      recommendation:
+        "Please whitelist our script in your performance optimization plugin to stop it from changing our snippet",
+      url: "https://plausible.io/wordpress-analytics-plugin "
+    },
+    illegal_attrs_wp_no_plugin: %{
+      message: "A performance optimization plugin seems to have altered our snippet",
+      recommendation:
+        "Please install and activate our WordPress plugin to avoid the most common plugin conflicts",
+      url: "https://plausible.io/wordpress-analytics-plugin "
+    },
+    illegal_attrs_general: %{
+      message: "Something seems to have altered our snippet",
+      recommendation:
+        "Please manually check your integration to make sure that nothing prevents our script from working",
+      url: "https://plausible.io/docs/troubleshoot-integration"
+    },
+    unknown: %{
+      message: "Your Plausible integration is not working",
+      recommendation:
+        "Please manually check your integration to make sure that the Plausible snippet has been inserted correctly",
+      url: "https://plausible.io/docs/troubleshoot-integration"
+    }
+  }
+
+  def all(), do: @errors
+end
diff --git a/test/plausible/site/verification/checks_test.exs b/test/plausible/site/verification/checks_test.exs
index a80d3c034bc7..3838b9860c9b 100644
--- a/test/plausible/site/verification/checks_test.exs
+++ b/test/plausible/site/verification/checks_test.exs
@@ -7,6 +7,8 @@ defmodule Plausible.Verification.ChecksTest do
   import ExUnit.CaptureLog
   import Plug.Conn
 
+  @errors Plausible.Verification.Errors.all()
+
   @normal_body """
   <html>
   <head>
@@ -21,32 +23,18 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(200, @normal_body)
       stub_installation()
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      assert interpretation.ok?
-      assert interpretation.errors == []
-      assert interpretation.recommendations == []
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_ok()
     end
 
     test "service error - 400" do
       stub_fetch_body(200, @normal_body)
       stub_installation(400, %{})
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-
-      assert interpretation.errors == [
-               "We encountered a temporary problem verifying your website"
-             ]
-
-      assert interpretation.recommendations == [
-               {"Please try again in a few minutes or manually check your integration",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.temporary)
     end
 
     @tag :slow
@@ -54,23 +42,16 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(500, "")
       stub_installation()
 
-      {result, log} =
+      {_, log} =
         with_log(fn ->
           run_checks()
+          |> Checks.interpret_diagnostics()
+          |> assert_error(@errors.unreachable, url: "https://example.com")
         end)
 
       assert log =~ "3 attempts left"
       assert log =~ "2 attempts left"
       assert log =~ "1 attempt left"
-
-      interpretation = Checks.interpret_diagnostics(result)
-      refute interpretation.ok?
-      assert interpretation.errors == ["We couldn't reach https://example.com. Is your site up?"]
-
-      assert interpretation.recommendations == [
-               {"If your site is running at a different location, please manually check your integration",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
     end
 
     test "fetching will follow 2 redirects" do
@@ -94,15 +75,13 @@ defmodule Plausible.Verification.ChecksTest do
 
       stub_installation()
 
-      result = run_checks()
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_ok()
+
       assert_receive :redirect_sent
       assert_receive :redirect_sent
       refute_receive _
-
-      interpretation = Checks.interpret_diagnostics(result)
-      assert interpretation.ok?
-      assert interpretation.errors == []
-      assert interpretation.recommendations == []
     end
 
     test "fetching will give up at 5th redirect" do
@@ -118,7 +97,9 @@ defmodule Plausible.Verification.ChecksTest do
 
       stub_installation()
 
-      result = run_checks()
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.unreachable, url: "https://example.com")
 
       assert_receive :redirect_sent
       assert_receive :redirect_sent
@@ -126,31 +107,15 @@ defmodule Plausible.Verification.ChecksTest do
       assert_receive :redirect_sent
       assert_receive :redirect_sent
       refute_receive _
-
-      interpretation = Checks.interpret_diagnostics(result)
-      refute interpretation.ok?
-      assert interpretation.errors == ["We couldn't reach https://example.com. Is your site up?"]
-
-      assert interpretation.recommendations == [
-               {"If your site is running at a different location, please manually check your integration",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
     end
 
     test "fetching body fails at non-2xx status, but installation is ok" do
       stub_fetch_body(599, "boo")
       stub_installation()
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      refute interpretation.ok?
-      assert interpretation.errors == ["We couldn't reach https://example.com. Is your site up?"]
-
-      assert interpretation.recommendations == [
-               {"If your site is running at a different location, please manually check your integration",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.unreachable, url: "https://example.com")
     end
 
     @snippet_in_body """
@@ -168,16 +133,9 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(200, @snippet_in_body)
       stub_installation()
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-      assert interpretation.errors == ["Plausible snippet is placed in the body of your site"]
-
-      assert interpretation.recommendations == [
-               {"Please relocate the snippet to the header of your site",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.snippet_in_body)
     end
 
     @many_snippets """
@@ -200,16 +158,9 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(200, @many_snippets)
       stub_installation()
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-      assert interpretation.errors == ["We've found multiple Plausible snippets on your site."]
-
-      assert interpretation.recommendations == [
-               {"Please ensure that only one snippet is used",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.multiple_snippets)
     end
 
     @body_no_snippet """
@@ -249,16 +200,9 @@ defmodule Plausible.Verification.ChecksTest do
         end
       end)
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      refute interpretation.ok?
-      assert interpretation.errors == ["We encountered an issue with your site cache"]
-
-      assert interpretation.recommendations == [
-               {"Please clear your cache (or wait for your provider to clear it) to ensure that the latest version of your site is being displayed to all your visitors",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.cache_general)
     end
 
     @normal_body_wordpress """
@@ -298,16 +242,9 @@ defmodule Plausible.Verification.ChecksTest do
         end
       end)
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      refute interpretation.ok?
-      assert interpretation.errors == ["We encountered an issue with your site cache"]
-
-      assert interpretation.recommendations == [
-               {"Please install and activate our WordPress plugin to start counting your visitors",
-                "https://plausible.io/wordpress-analytics-plugin"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.cache_wp_no_plugin)
     end
 
     @normal_body_wordpress_official_plugin """
@@ -348,32 +285,18 @@ defmodule Plausible.Verification.ChecksTest do
         end
       end)
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      refute interpretation.ok?
-      assert interpretation.errors == ["We encountered an issue with your site cache"]
-
-      assert interpretation.recommendations == [
-               {"Please clear your WordPress cache to ensure that the latest version of your site is being displayed to all your visitors",
-                "https://plausible.io/wordpress-analytics-plugin"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.cache_wp_plugin)
     end
 
     test "detecting no snippet" do
       stub_fetch_body(200, @body_no_snippet)
       stub_installation(200, plausible_installed(false))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-      assert interpretation.errors == ["We couldn't find the Plausible snippet on your site"]
-
-      assert interpretation.recommendations == [
-               {"Please insert the snippet into your site",
-                "https://plausible.io/docs/plausible-script"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.no_snippet)
     end
 
     test "a check that raises" do
@@ -395,15 +318,9 @@ defmodule Plausible.Verification.ChecksTest do
       assert log =~
                ~s|Error running check Plausible.Verification.ChecksTest.FaultyCheckRaise on https://example.com: %RuntimeError{message: "boom"}|
 
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-      assert interpretation.errors == ["We couldn't reach https://example.com. Is your site up?"]
-
-      assert interpretation.recommendations == [
-               {"If your site is running at a different location, please manually check your integration",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      result
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.unreachable, url: "https://example.com")
     end
 
     test "a check that throws" do
@@ -425,14 +342,9 @@ defmodule Plausible.Verification.ChecksTest do
       assert log =~
                ~s|Error running check Plausible.Verification.ChecksTest.FaultyCheckThrow on https://example.com: :boom|
 
-      interpretation = Checks.interpret_diagnostics(result)
-      refute interpretation.ok?
-      assert interpretation.errors == ["We couldn't reach https://example.com. Is your site up?"]
-
-      assert interpretation.recommendations == [
-               {"If your site is running at a different location, please manually check your integration",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      result
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.unreachable, url: "https://example.com")
     end
 
     test "disallowed via content-security-policy" do
@@ -445,19 +357,9 @@ defmodule Plausible.Verification.ChecksTest do
 
       stub_installation(200, plausible_installed(false))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-
-      assert interpretation.errors == ["We encountered an issue with your site's CSP"]
-
-      assert interpretation.recommendations == [
-               {
-                 "Please add plausible.io domain specifically to the allowed list of domains in your Content Security Policy (CSP)",
-                 "https://plausible.io/docs/troubleshoot-integration"
-               }
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.csp)
     end
 
     test "disallowed via content-security-policy with no snippet should make the latter a priority" do
@@ -470,12 +372,9 @@ defmodule Plausible.Verification.ChecksTest do
 
       stub_installation(200, plausible_installed(false))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-
-      assert interpretation.errors == ["We couldn't find the Plausible snippet on your site"]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.no_snippet)
     end
 
     test "allowed via content-security-policy" do
@@ -493,13 +392,10 @@ defmodule Plausible.Verification.ChecksTest do
       end)
 
       stub_installation()
-      result = run_checks()
 
-      interpretation = Checks.interpret_diagnostics(result)
-
-      assert interpretation.ok?
-      assert interpretation.errors == []
-      assert interpretation.recommendations == []
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_ok()
     end
 
     test "running checks sends progress messages" do
@@ -539,16 +435,9 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(200, @gtm_body)
       stub_installation(200, plausible_installed(false))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-      assert interpretation.errors == ["We encountered an issue with your Plausible integration"]
-
-      assert interpretation.recommendations == [
-               {"As you're using Google Tag Manager, you'll need to use a GTM-specific Plausible snippet",
-                "https://plausible.io/docs/google-tag-manager"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.gtm)
     end
 
     test "non-html body" do
@@ -560,16 +449,9 @@ defmodule Plausible.Verification.ChecksTest do
 
       stub_installation(200, plausible_installed(false))
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      refute interpretation.ok?
-      assert interpretation.errors == ["We couldn't reach https://example.com. Is your site up?"]
-
-      assert interpretation.recommendations == [
-               {"If your site is running at a different location, please manually check your integration",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.unreachable, url: "https://example.com")
     end
 
     @proxied_script_body """
@@ -585,28 +467,18 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(200, @proxied_script_body)
       stub_installation()
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      assert interpretation.ok?
-      assert interpretation.errors == []
-      assert interpretation.recommendations == []
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_ok()
     end
 
     test "proxied setup, function defined but callback won't fire" do
       stub_fetch_body(200, @proxied_script_body)
       stub_installation(200, plausible_installed(true, 0))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-      assert interpretation.errors == ["We encountered an error with your Plausible proxy"]
-
-      assert interpretation.recommendations == [
-               {"Please check whether you've configured the /event route correctly",
-                "https://plausible.io/docs/proxy/introduction"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.proxy_misconfigured)
     end
 
     @proxied_script_body_wordpress """
@@ -623,17 +495,9 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(200, @proxied_script_body_wordpress)
       stub_installation(200, plausible_installed(false, 0))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-      assert interpretation.errors == ["We encountered an error with your Plausible proxy"]
-
-      assert interpretation.recommendations ==
-               [
-                 {"Please re-enable the proxy in our WordPress plugin to start counting your visitors",
-                  "https://plausible.io/wordpress-analytics-plugin"}
-               ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.proxy_wp_no_plugin)
     end
 
     test "proxied setup, function undefined, callback won't fire" do
@@ -646,27 +510,18 @@ defmodule Plausible.Verification.ChecksTest do
       refute interpretation.ok?
       assert interpretation.errors == ["We encountered an error with your Plausible proxy"]
 
-      assert interpretation.recommendations ==
-               [
-                 {"Please check your proxy configuration to make sure it's set up correctly",
-                  "https://plausible.io/docs/proxy/introduction"}
-               ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.proxy_general)
     end
 
     test "non-proxied setup, but callback fails to fire" do
       stub_fetch_body(200, @normal_body)
       stub_installation(200, plausible_installed(true, 0))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-      assert interpretation.errors == ["Your Plausible integration is not working"]
-
-      assert interpretation.recommendations == [
-               {"Please manually check your integration to make sure that the Plausible snippet has been inserted correctly",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.unknown)
     end
 
     @body_unknown_attributes """
@@ -682,16 +537,9 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(200, @body_unknown_attributes)
       stub_installation(200, plausible_installed(false, 0))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-      assert interpretation.errors == ["Something seems to have altered our snippet"]
-
-      assert interpretation.recommendations == [
-               {"Please manually check your integration to make sure that nothing prevents our script from working",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.illegal_attrs_general)
     end
 
     @body_unknown_attributes_wordpress """
@@ -708,19 +556,9 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(200, @body_unknown_attributes_wordpress)
       stub_installation(200, plausible_installed(false, 0))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-
-      assert interpretation.errors == [
-               "A performance optimization plugin seems to have altered our snippet"
-             ]
-
-      assert interpretation.recommendations == [
-               {"Please install and activate our WordPress plugin to avoid the most common plugin conflicts",
-                "https://plausible.io/wordpress-analytics-plugin "}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.illegal_attrs_wp_no_plugin)
     end
 
     @body_unknown_attributes_wordpress_official_plugin """
@@ -738,94 +576,54 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(200, @body_unknown_attributes_wordpress_official_plugin)
       stub_installation(200, plausible_installed(false, 0))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      refute interpretation.ok?
-
-      assert interpretation.errors == [
-               "A performance optimization plugin seems to have altered our snippet"
-             ]
-
-      assert interpretation.recommendations == [
-               {"Please whitelist our script in your performance optimization plugin to stop it from changing our snippet",
-                "https://plausible.io/wordpress-analytics-plugin "}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.illegal_attrs_wp_plugin)
     end
 
     test "callback handling not found for non-wordpress site" do
       stub_fetch_body(200, @normal_body)
       stub_installation(200, plausible_installed(true, -1))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      assert interpretation.errors == ["We encountered a problem trying to verify your website"]
-
-      assert interpretation.recommendations == [
-               {"The integration may be working but as you're running an older version of our script, we cannot verify it automatically. Please manually check your integration or update to use the latest script",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.old_script)
     end
 
     test "callback handling not found for wordpress site" do
       stub_fetch_body(200, @normal_body_wordpress)
       stub_installation(200, plausible_installed(true, -1))
 
-      result = run_checks()
-      interpretation = Checks.interpret_diagnostics(result)
-
-      assert interpretation.errors == ["We encountered a problem trying to verify your website"]
-
-      assert interpretation.recommendations == [
-               {"The integration may be working but as you're running an older version of our script, we cannot verify it automatically. Please install our WordPress plugin to use the built-in proxy",
-                "https://plausible.io/wordpress-analytics-plugin"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.old_script_wp_no_plugin)
     end
 
     test "callback handling not found for wordpress site using our plugin" do
       stub_fetch_body(200, @normal_body_wordpress_official_plugin)
       stub_installation(200, plausible_installed(true, -1))
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      assert interpretation.errors == ["We encountered a problem trying to verify your website"]
-
-      assert interpretation.recommendations == [
-               {
-                 "The integration may be working but as you're running an older version of our script, we cannot verify it automatically. Please disable and then enable the proxy in our WordPress plugin, then clear your WordPress cache",
-                 "https://plausible.io/wordpress-analytics-plugin"
-               }
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.old_script_wp_plugin)
     end
 
     test "non-standard integration where the snippet cannot be found but it works ok in headless" do
       stub_fetch_body(200, @body_no_snippet)
       stub_installation(200, plausible_installed(true, 202))
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      assert interpretation.ok?
-      assert interpretation.errors == []
-      assert interpretation.recommendations == []
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_ok()
     end
 
     test "fails due to callback status being something unlikely like 500" do
       stub_fetch_body(200, @normal_body)
       stub_installation(200, plausible_installed(true, 500))
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      refute interpretation.ok?
-      assert interpretation.errors == ["Your Plausible integration is not working"]
-
-      assert interpretation.recommendations == [
-               {"Please manually check your integration to make sure that the Plausible snippet has been inserted correctly",
-                "https://plausible.io/docs/troubleshoot-integration"}
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.unknown)
     end
 
     @different_data_domain_body """
@@ -841,18 +639,9 @@ defmodule Plausible.Verification.ChecksTest do
       stub_fetch_body(200, @different_data_domain_body)
       stub_installation()
 
-      result = run_checks()
-
-      interpretation = Checks.interpret_diagnostics(result)
-      refute interpretation.ok?
-      assert interpretation.errors == ["Your data-domain is different than example.com"]
-
-      assert interpretation.recommendations == [
-               {
-                 "Please ensure that the site in the data-domain attribute is an exact match to the site as you added it to your Plausible account",
-                 "https://plausible.io/docs/troubleshoot-integration"
-               }
-             ]
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_error(@errors.different_data_domain, domain: "example.com")
     end
 
     test "data-domain mismatch on redirect chain" do
@@ -876,14 +665,11 @@ defmodule Plausible.Verification.ChecksTest do
 
       stub_installation()
 
-      result = run_checks()
+      run_checks()
+      |> Checks.interpret_diagnostics()
+      |> assert_ok()
 
       assert_receive :redirect_sent
-
-      interpretation = Checks.interpret_diagnostics(result)
-      assert interpretation.ok?
-      assert interpretation.errors == []
-      assert interpretation.recommendations == []
     end
   end
 
@@ -922,4 +708,27 @@ defmodule Plausible.Verification.ChecksTest do
   defp plausible_installed(bool \\ true, callback_status \\ 202) do
     %{"data" => %{"plausibleInstalled" => bool, "callbackStatus" => callback_status}}
   end
+
+  defp assert_error(interpretation, error) do
+    refute interpretation.ok?
+
+    assert interpretation.errors == [
+             error.message
+           ]
+
+    assert interpretation.recommendations == [
+             {error.recommendation, error.url}
+           ]
+  end
+
+  defp assert_error(interpretation, error, assigns) do
+    message = EEx.eval_string(error.message, assigns: assigns)
+    assert_error(interpretation, %{error | message: message})
+  end
+
+  defp assert_ok(interpretation) do
+    assert interpretation.ok?
+    assert interpretation.errors == []
+    assert interpretation.recommendations == []
+  end
 end