Skip to content

Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.

Script v2: Add more diagnostics cases to verifier v2, more tests for verifier v2 (#5620)

Artur Pataa2df9a986c2a
diff --git a/lib/plausible/installation_support/verification/diagnostics.ex b/lib/plausible/installation_support/verification/diagnostics.ex
index 24b0cc64a2..3f3d581816 100644
--- a/lib/plausible/installation_support/verification/diagnostics.ex
+++ b/lib/plausible/installation_support/verification/diagnostics.ex
@@ -50,13 +50,6 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics do
end
end
- @error_unexpected_domain Error.new!(%{
- message: "Plausible test event is not for this site",
- recommendation:
- "Please check that the snippet on your site matches the installation instructions exactly",
- url:
- "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"
- })
@error_succeeds_only_after_cache_bust Error.new!(%{
message: "We detected an issue with your site's cache",
recommendation:
@@ -64,6 +57,7 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics do
url:
"https://plausible.io/docs/troubleshoot-integration#have-you-cleared-the-cache-of-your-site"
})
+
@spec interpret(t(), String.t(), String.t()) :: Result.t()
def interpret(
%__MODULE__{
@@ -76,26 +70,95 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics do
"responseStatus" => response_status
},
service_error: nil,
- diagnostics_are_from_cache_bust: diagnostics_are_from_cache_bust
- } = diagnostics,
+ diagnostics_are_from_cache_bust: true
+ },
expected_domain,
- url
+ _url
)
- when response_status in [200, 202] do
- domain_is_expected? = domain == expected_domain
+ when response_status in [200, 202] and
+ domain == expected_domain,
+ do: error(@error_succeeds_only_after_cache_bust)
- cond do
- domain_is_expected? and diagnostics_are_from_cache_bust ->
- error(@error_succeeds_only_after_cache_bust)
+ def interpret(
+ %__MODULE__{
+ plausible_is_on_window: true,
+ plausible_is_initialized: true,
+ test_event: %{
+ "normalizedBody" => %{
+ "domain" => domain
+ },
+ "responseStatus" => response_status
+ },
+ service_error: nil
+ },
+ expected_domain,
+ _url
+ )
+ when response_status in [200, 202] and
+ domain == expected_domain,
+ do: success()
- domain_is_expected? ->
- success()
+ @error_unexpected_domain Error.new!(%{
+ message: "Plausible test event is not for this site",
+ recommendation:
+ "Please check that the snippet on your site matches the installation instructions exactly",
+ url:
+ "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"
+ })
+ def interpret(
+ %__MODULE__{
+ plausible_is_on_window: true,
+ plausible_is_initialized: true,
+ test_event: %{
+ "normalizedBody" => %{
+ "domain" => domain
+ },
+ "responseStatus" => response_status
+ },
+ service_error: nil
+ },
+ expected_domain,
+ _url
+ )
+ when response_status in [200, 202] and
+ domain != expected_domain,
+ do: error(@error_unexpected_domain)
+
+ @error_proxy_network_error Error.new!(%{
+ message:
+ "We got an unexpected response from the proxy you are using for Plausible",
+ recommendation:
+ "Please check that you've configured the proxied /event route correctly",
+ url: "https://plausible.io/docs/proxy/introduction"
+ })
+ @error_plausible_network_error Error.new!(%{
+ message: "We couldn't verify your website",
+ recommendation:
+ "Please try verifying again in a few minutes, or verify your installation manually",
+ url:
+ "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"
+ })
- not domain_is_expected? ->
- error(@error_unexpected_domain)
+ def interpret(
+ %__MODULE__{
+ plausible_is_on_window: true,
+ plausible_is_initialized: true,
+ test_event: %{
+ "requestUrl" => request_url,
+ "responseStatus" => response_status
+ },
+ service_error: nil
+ },
+ _expected_domain,
+ _url
+ )
+ when response_status not in [200, 202] and is_binary(request_url) do
+ proxying? = not String.starts_with?(request_url, PlausibleWeb.Endpoint.url())
- true ->
- unknown_error(diagnostics, url)
+ if proxying? do
+ error(@error_proxy_network_error)
+ else
+ error(@error_plausible_network_error)
end
end
@@ -114,9 +177,26 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics do
},
_expected_domain,
_url
- ) do
- error(@error_csp_disallowed)
- end
+ ),
+ do: error(@error_csp_disallowed)
+
+ @error_gtm_selected_maybe_cookie_banner Error.new!(%{
+ message: "We couldn't verify your website",
+ recommendation:
+ "A cookie consent banner may be stopping Plausible from loading on your site. If that is intentional, you'll need to verify that Plausible works manually",
+ url:
+ "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"
+ })
+ def interpret(
+ %__MODULE__{
+ selected_installation_type: "gtm",
+ cookie_banner_likely: true,
+ service_error: nil
+ },
+ _expected_domain,
+ _url
+ ),
+ do: error(@error_gtm_selected_maybe_cookie_banner)
def interpret(%__MODULE__{} = diagnostics, _expected_domain, url),
do: unknown_error(diagnostics, url)
diff --git a/test/plausible/installation_support/verification/diagnostics_test.exs b/test/plausible/installation_support/verification/diagnostics_test.exs
new file mode 100644
index 0000000000..fd83643778
--- /dev/null
+++ b/test/plausible/installation_support/verification/diagnostics_test.exs
@@ -0,0 +1,211 @@
+defmodule Plausible.InstallationSupport.Verification.DiagnosticsTest do
+ use ExUnit.Case
+ import Plausible.AssertMatches
+ alias Plausible.InstallationSupport.Verification.Diagnostics
+ alias Plausible.InstallationSupport.Result
+
+ describe "interpreting diagnostics" do
+ for status <- [200, 202] do
+ test "success with response status #{status}" do
+ expected_domain = "example.com"
+ url_to_verify = "https://#{expected_domain}"
+
+ diagnostics = %Diagnostics{
+ plausible_is_on_window: true,
+ plausible_is_initialized: true,
+ test_event: %{
+ "normalizedBody" => %{
+ "domain" => "example.com"
+ },
+ "responseStatus" => unquote(status)
+ },
+ service_error: nil
+ }
+
+ assert Diagnostics.interpret(diagnostics, expected_domain, url_to_verify) == %Result{
+ ok?: true
+ }
+ end
+ end
+
+ test "error when it 'succeeds', but only after cache bust" do
+ expected_domain = "example.com"
+ url_to_verify = "https://#{expected_domain}"
+
+ diagnostics = %Diagnostics{
+ plausible_is_on_window: true,
+ plausible_is_initialized: true,
+ test_event: %{
+ "normalizedBody" => %{
+ "domain" => "example.com"
+ },
+ "responseStatus" => 200
+ },
+ diagnostics_are_from_cache_bust: true,
+ service_error: nil
+ }
+
+ assert_matches %Result{
+ ok?: false,
+ errors: [^any(:string, ~r/.*cache.*/)],
+ recommendations: [
+ %{
+ text: ^any(:string, ~r/.*cache.*/),
+ url:
+ "https://plausible.io/docs/troubleshoot-integration#have-you-cleared-the-cache-of-your-site"
+ }
+ ]
+ } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)
+ end
+
+ test "error when test event domain doesn't match expected domain" do
+ expected_domain = "example.com"
+ url_to_verify = "https://#{expected_domain}"
+
+ diagnostics = %Diagnostics{
+ plausible_is_on_window: true,
+ plausible_is_initialized: true,
+ test_event: %{
+ "normalizedBody" => %{
+ "domain" => "wrong-domain.com"
+ },
+ "responseStatus" => 200
+ },
+ service_error: nil
+ }
+
+ assert_matches %Result{
+ ok?: false,
+ errors: [^any(:string, ~r/.*not for this site.*/)],
+ recommendations: [
+ %{
+ text: ^any(:string, ~r/.*snippet.*/),
+ url:
+ "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"
+ }
+ ]
+ } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)
+ end
+
+ test "error when proxy network error occurs" do
+ expected_domain = "example.com"
+ url_to_verify = "https://#{expected_domain}"
+
+ diagnostics = %Diagnostics{
+ plausible_is_on_window: true,
+ plausible_is_initialized: true,
+ test_event: %{
+ "requestUrl" => "https://proxy.example.com/event",
+ "responseStatus" => 500
+ },
+ service_error: nil
+ }
+
+ assert_matches %Result{
+ ok?: false,
+ errors: [^any(:string, ~r/.*proxy.*/)],
+ recommendations: [
+ %{
+ text: ^any(:string, ~r/.*proxied.*/),
+ url: "https://plausible.io/docs/proxy/introduction"
+ }
+ ]
+ } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)
+ end
+
+ test "error when plausible network error occurs" do
+ expected_domain = "example.com"
+ url_to_verify = "https://#{expected_domain}"
+
+ diagnostics = %Diagnostics{
+ plausible_is_on_window: true,
+ plausible_is_initialized: true,
+ test_event: %{
+ "requestUrl" => PlausibleWeb.Endpoint.url() <> "/api/event",
+ "responseStatus" => 500
+ },
+ service_error: nil
+ }
+
+ assert_matches %Result{
+ ok?: false,
+ errors: [^any(:string, ~r/.*couldn't verify.*/)],
+ recommendations: [
+ %{
+ text: ^any(:string, ~r/.*try verifying again.*/),
+ url:
+ "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"
+ }
+ ]
+ } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)
+ end
+
+ test "error when disallowed by CSP" do
+ expected_domain = "example.com"
+ url_to_verify = "https://#{expected_domain}"
+
+ diagnostics = %Diagnostics{
+ disallowed_by_csp: true,
+ service_error: nil
+ }
+
+ assert_matches %Result{
+ ok?: false,
+ errors: [^any(:string, ~r/.*Content Security Policy.*/)],
+ recommendations: [
+ %{
+ text: ^any(:string, ~r/.*plausible\.io domain.*/),
+ url:
+ "https://plausible.io/docs/troubleshoot-integration#does-your-site-use-a-content-security-policy-csp"
+ }
+ ]
+ } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)
+ end
+
+ test "error when GTM selected and cookie banner likely" do
+ expected_domain = "example.com"
+ url_to_verify = "https://#{expected_domain}"
+
+ diagnostics = %Diagnostics{
+ selected_installation_type: "gtm",
+ cookie_banner_likely: true,
+ service_error: nil
+ }
+
+ assert_matches %Result{
+ ok?: false,
+ errors: [^any(:string, ~r/.*couldn't verify.*/)],
+ recommendations: [
+ %{
+ text: ^any(:string, ~r/.*cookie consent banner.*/),
+ url:
+ "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"
+ }
+ ]
+ } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)
+ end
+
+ test "unknown error when no specific case matches" do
+ expected_domain = "example.com"
+ url_to_verify = "https://#{expected_domain}"
+
+ diagnostics = %Diagnostics{
+ plausible_is_on_window: false,
+ plausible_is_initialized: false,
+ service_error: nil
+ }
+
+ assert_matches %Result{
+ ok?: false,
+ errors: [^any(:string, ~r/.*integration is not working.*/)],
+ recommendations: [
+ %{
+ text: ^any(:string, ~r/.*manually check.*/),
+ url:
+ "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"
+ }
+ ]
+ } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)
+ end
+ end
+end
diff --git a/tracker/test/installation_support/verifier-v2.spec.ts b/tracker/test/installation_support/verifier-v2.spec.ts
index 50f868504f..6dfe826c62 100644
--- a/tracker/test/installation_support/verifier-v2.spec.ts
+++ b/tracker/test/installation_support/verifier-v2.spec.ts
@@ -37,9 +37,13 @@ test.describe('installed plausible web variant', () => {
bodyContent: ''
})
- await page.goto(url)
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
- const result = await executeVerifyV2(page, DEFAULT_VERIFICATION_OPTIONS)
+ const result = await executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ responseHeaders
+ })
expect(result).toEqual({
data: {
@@ -93,10 +97,12 @@ test.describe('installed plausible web variant', () => {
bodyContent: ''
})
- await page.goto(url)
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
const result = await executeVerifyV2(page, {
...DEFAULT_VERIFICATION_OPTIONS,
+ responseHeaders,
timeoutMs
})
@@ -149,9 +155,13 @@ test.describe('installed plausible web variant', () => {
bodyContent: ''
})
- await page.goto(url)
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
- const result = await executeVerifyV2(page, DEFAULT_VERIFICATION_OPTIONS)
+ const result = await executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ responseHeaders
+ })
expect(result).toEqual({
data: {
@@ -191,9 +201,13 @@ test.describe('installed plausible web variant', () => {
bodyContent: ''
})
- await page.goto(url)
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
- const result = await executeVerifyV2(page, DEFAULT_VERIFICATION_OPTIONS)
+ const result = await executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ responseHeaders
+ })
expect(result).toEqual({
data: {
@@ -236,11 +250,16 @@ test.describe('installed plausible web variant', () => {
bodyContent: 'alfa'
})
- await page.goto(url)
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
+
await expect(page.getByText('alfa')).toBeVisible()
const [result, _] = await Promise.all([
- executeVerifyV2(page, DEFAULT_VERIFICATION_OPTIONS),
+ executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ responseHeaders
+ }),
page.evaluate(
({ targetUrl }) =>
setTimeout(() => (window.location.href = targetUrl), 250),
@@ -307,14 +326,17 @@ test.describe('installed plausible web variant', () => {
bodyContent: 'alfa'
})
- await page.goto(url)
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
+
await expect(page.getByText('alfa')).toBeVisible()
const [result] = await Promise.all([
executeVerifyV2(page, {
...DEFAULT_VERIFICATION_OPTIONS,
timeoutBetweenAttemptsMs,
- maxAttempts
+ maxAttempts,
+ responseHeaders
}),
page.evaluate(
(url) => setTimeout(() => (window.location.href = url), 250),
@@ -334,6 +356,187 @@ test.describe('installed plausible web variant', () => {
}
})
})
+
+ test('using provided snippet but disallowed by CSP', async ({ page }, {
+ testId
+ }) => {
+ await mockManyRequests({
+ page,
+ path: `https://plausible.io/api/event`,
+ awaitedRequestCount: 1,
+ fulfill: {
+ status: 202,
+ contentType: 'text/plain',
+ body: 'ok'
+ }
+ })
+
+ const { url } = await initializePageDynamically(page, {
+ testId,
+ scriptConfig: {
+ domain: 'example.com',
+ endpoint: `https://plausible.io/api/event`,
+ captureOnLocalhost: true
+ },
+ bodyContent: '',
+ headers: {
+ 'content-security-policy': "default-src 'self'; img-src 'self'"
+ }
+ })
+
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
+
+ const result = await executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ responseHeaders
+ })
+
+ expect(result).toEqual({
+ data: {
+ attempts: 1,
+ completed: true,
+ disallowedByCsp: true,
+ plausibleIsOnWindow: false,
+ plausibleIsInitialized: undefined,
+ plausibleVersion: undefined,
+ plausibleVariant: undefined,
+ testEvent: {
+ error: undefined,
+ normalizedBody: undefined,
+ requestUrl: undefined,
+ responseStatus: undefined
+ },
+ cookieBannerLikely: false
+ }
+ })
+ })
+
+ test(`using provided snippet and there is a strict CSP without 'unsafe-inline'`, async ({
+ page
+ }, { testId }) => {
+ const endpoint = `${LOCAL_SERVER_ADDR}/api/event`
+ const cspHostToCheck = LOCAL_SERVER_ADDR.replace('http://', '')
+ const headers = {
+ // 'unsafe-inline' is needed to allow the bootstrapper snippet to be executed
+ 'content-security-policy': `default-src 'self'; script-src ${cspHostToCheck}; connect-src ${cspHostToCheck}`
+ }
+
+ await mockManyRequests({
+ page,
+ path: endpoint,
+ awaitedRequestCount: 1,
+ fulfill: {
+ status: 202,
+ contentType: 'text/plain',
+ body: 'ok'
+ }
+ })
+
+ const { url } = await initializePageDynamically(page, {
+ testId,
+ scriptConfig: {
+ endpoint,
+ domain: 'example.com',
+ captureOnLocalhost: true
+ },
+ bodyContent: '',
+ headers
+ })
+
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
+
+ const result = await executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ cspHostToCheck,
+ responseHeaders
+ })
+
+ expect(result).toEqual({
+ data: {
+ attempts: 1,
+ completed: true,
+ disallowedByCsp: false, // scripts from our domain are allowed, but the inline sourceless snippet can't run because 'unsafe-inline' is not present in the CSP
+ plausibleIsOnWindow: false,
+ plausibleIsInitialized: undefined,
+ plausibleVersion: undefined,
+ plausibleVariant: undefined,
+ testEvent: {
+ error: undefined,
+ normalizedBody: undefined,
+ requestUrl: undefined,
+ responseStatus: undefined
+ },
+ cookieBannerLikely: false
+ }
+ })
+ })
+
+ test(`using provided snippet and there is a strict CSP with 'unsafe-inline'`, async ({
+ page
+ }, { testId }) => {
+ const endpoint = `${LOCAL_SERVER_ADDR}/api/event`
+ const cspHostToCheck = LOCAL_SERVER_ADDR.replace('http://', '')
+ const headers = {
+ // 'unsafe-inline' is needed to allow the bootstrapper snippet to be executed
+ 'content-security-policy': `default-src 'self'; script-src 'unsafe-inline' ${cspHostToCheck}; connect-src ${cspHostToCheck}`
+ }
+
+ await mockManyRequests({
+ page,
+ path: endpoint,
+ awaitedRequestCount: 1,
+ fulfill: {
+ status: 202,
+ contentType: 'text/plain',
+ body: 'ok'
+ }
+ })
+
+ const { url } = await initializePageDynamically(page, {
+ testId,
+ scriptConfig: {
+ endpoint,
+ domain: 'example.com',
+ captureOnLocalhost: true
+ },
+ bodyContent: '',
+ headers
+ })
+
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
+
+ const result = await executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ cspHostToCheck,
+ responseHeaders
+ })
+
+ expect(result).toEqual({
+ data: {
+ attempts: 1,
+ completed: true,
+ disallowedByCsp: false,
+ plausibleIsOnWindow: true,
+ plausibleIsInitialized: true,
+ plausibleVersion: version,
+ plausibleVariant: 'web',
+ testEvent: {
+ callbackResult: { status: 202 },
+ requestUrl: `${LOCAL_SERVER_ADDR}/api/event`,
+ normalizedBody: {
+ domain: 'example.com',
+ name: 'verification-agent-test',
+ version
+ },
+ responseStatus: 202
+ },
+ cookieBannerLikely: false
+ }
+ })
+ })
})
test.describe('installed plausible esm variant', () => {
@@ -361,9 +564,13 @@ test.describe('installed plausible esm variant', () => {
bodyContent: ''
})
- await page.goto(url)
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
- const result = await executeVerifyV2(page, DEFAULT_VERIFICATION_OPTIONS)
+ const result = await executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ responseHeaders
+ })
expect(result).toEqual({
data: {
@@ -416,9 +623,13 @@ test.describe('installed plausible esm variant', () => {
bodyContent: ''
})
- await page.goto(url)
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
- const result = await executeVerifyV2(page, DEFAULT_VERIFICATION_OPTIONS)
+ const result = await executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ responseHeaders
+ })
expect(result).toEqual({
data: {
@@ -471,9 +682,13 @@ test.describe('installed plausible esm variant', () => {
}
})
- await page.goto(url)
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
- const result = await executeVerifyV2(page, DEFAULT_VERIFICATION_OPTIONS)
+ const result = await executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ responseHeaders
+ })
expect(result).toEqual({
data: {
@@ -515,9 +730,13 @@ test.describe('installed plausible esm variant', () => {
bodyContent: ''
})
- await page.goto(url)
+ const response = await page.goto(url)
+ const responseHeaders = response?.headers() ?? {}
- const result = await executeVerifyV2(page, DEFAULT_VERIFICATION_OPTIONS)
+ const result = await executeVerifyV2(page, {
+ ...DEFAULT_VERIFICATION_OPTIONS,
+ responseHeaders
+ })
expect(result).toEqual({
data: {
diff --git a/tracker/test/support/initialize-page-dynamically.ts b/tracker/test/support/initialize-page-dynamically.ts
index 52a9154b1e..6a2f7fa655 100644
--- a/tracker/test/support/initialize-page-dynamically.ts
+++ b/tracker/test/support/initialize-page-dynamically.ts
@@ -7,6 +7,7 @@ interface SharedOptions {
testId: string
/** optional path to append to the dynamic page URL */
path?: string
+ headers?: Record<string, string>
}
interface TemplatedResponse {
@@ -124,7 +125,8 @@ export async function initializePageDynamically(
await route.fulfill({
body: responseBody,
- contentType: 'text/html'
+ contentType: 'text/html',
+ headers: options.headers
})
})
return { url }