Shopifex.Test (Shopifex v3.0.0)

Copy Markdown View Source

Test helpers for apps built on Shopifex.

Shopifex authenticates requests with signed App Bridge session tokens and Shopify HMACs. To test your own controllers and LiveViews behind the :shopify_* pipelines, you need to produce those tokens/HMACs — which means re-implementing Shopifex's exact signing rules in your test suite. This module does it for you, reusing the same secret/algorithm Shopifex verifies against.

It ships with the library (it lives in lib/, not test/), so consuming apps can use it directly:

defmodule MyAppWeb.DashboardLiveTest do
  use MyAppWeb.ConnCase
  import Shopifex.Test

  test "renders for an authenticated shop", %{conn: conn} do
    shop = shop_fixture()

    conn = put_shopify_session(conn, shop)
    # conn now carries a valid Bearer id_token and current_shop is loaded
    # ...
  end
end

All functions default the secret/api_key to your :shopifex config; pass secret: / api_key: to override (e.g. to test :old_secret rotation).

Summary

Functions

Loads shop into the conn's Shopifex session and attaches a valid Authorization: Bearer <id_token> header, so the conn passes the :shopify_session / :shopify_api pipelines and current_shop/1 resolves.

Prepares a conn to pass the :shopify_webhook pipeline: assigns raw_body and sets a matching x-shopify-hmac-sha256 header. Identify the shop with the x-shopify-shop-domain request header (or a myshopify_domain in the signed body) — Shopifex.Plug.ShopifyWebhook resolves the shop from those, not from a query/body param a caller could shadow.

Returns the lowercase-hex HMAC for a query / app-proxy params map — the value Shopify sends in the hmac (admin load, &-joined) or signature (app proxy, empty joiner) parameter. Params are signed in Shopify's canonical sorted order.

Signs a valid Shopify App Bridge session token (id_token) for shop_url.

Returns the Base64 HMAC for a raw webhook body — the value Shopify sends in the x-shopify-hmac-sha256 header. Pass secret: to sign with a non-default key.

Functions

put_shopify_session(conn, shop, opts \\ [])

@spec put_shopify_session(Plug.Conn.t(), Shopifex.Plug.shop(), keyword()) ::
  Plug.Conn.t()

Loads shop into the conn's Shopifex session and attaches a valid Authorization: Bearer <id_token> header, so the conn passes the :shopify_session / :shopify_api pipelines and current_shop/1 resolves.

Accepts the same options as sign_session_token/2, plus :host / :locale.

put_webhook_hmac(conn, raw_body, opts \\ [])

@spec put_webhook_hmac(Plug.Conn.t(), binary(), keyword()) :: Plug.Conn.t()

Prepares a conn to pass the :shopify_webhook pipeline: assigns raw_body and sets a matching x-shopify-hmac-sha256 header. Identify the shop with the x-shopify-shop-domain request header (or a myshopify_domain in the signed body) — Shopifex.Plug.ShopifyWebhook resolves the shop from those, not from a query/body param a caller could shadow.

sign_query_hmac(params, opts \\ [])

@spec sign_query_hmac(map(), keyword()) :: String.t()

Returns the lowercase-hex HMAC for a query / app-proxy params map — the value Shopify sends in the hmac (admin load, &-joined) or signature (app proxy, empty joiner) parameter. Params are signed in Shopify's canonical sorted order.

Options

  • :secret — signing secret (default: config)
  • :joiner — "&" for hmac (default), "" for app-proxy signature

sign_session_token(shop_url, opts \\ [])

@spec sign_session_token(String.t(), keyword()) :: String.t()

Signs a valid Shopify App Bridge session token (id_token) for shop_url.

Options

  • :secret / :api_key — override the signing secret / audience (default: config)
  • :expires_in — seconds until exp (default 60)
  • :user_id — the sub (merchant user id) claim (default "1")
  • :claims — a map merged over the default claims (override exp, dest, …)

sign_webhook(raw_body, opts \\ [])

@spec sign_webhook(binary(), keyword()) :: String.t()

Returns the Base64 HMAC for a raw webhook body — the value Shopify sends in the x-shopify-hmac-sha256 header. Pass secret: to sign with a non-default key.