feature: add test sandbox mode

.github/workflows/elixir_tests.yml

@@ -24,14 +24,14 @@ jobs:
         image: "postgres:17-alpine"
         env:
           POSTGRES_PASSWORD: password
-          POSTGRES_DB: electric
+          POSTGRES_DB: phoenix_sync
         options: >-
           --health-cmd pg_isready
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
         ports:
-          - 54321:5432
+          - 55555:5432
 
     steps:
       - uses: actions/checkout@v4
@@ -60,7 +60,7 @@ jobs:
         with:
           path: |
             _build/*/lib
-            !_build/*/lib/electric_phoenix
+            !_build/*/lib/phoenix_sync
           key: ${{ runner.os }}-build-${{ env.MIX_ENV }}-[${{ github.ref_name }}]-${{ github.sha }}
           restore-keys: |
             ${{ runner.os }}-build-${{ env.MIX_ENV }}-[${{ github.ref_name }}]-${{ github.sha }}
@@ -77,9 +77,6 @@ jobs:
       - name: Run tests
         run: mix test --trace
 
-      - name: Test installation as a dependency
-        run: mix test.as_a_dep
-
   test-as-dep:
     name: Test installation as a dependency
     runs-on: ubuntu-latest
@@ -99,6 +96,38 @@ jobs:
       - name: Test installation as a dependency
         run: mix test.as_a_dep
 
+  test-apps:
+    name: Test integration apps
+    runs-on: ubuntu-latest
+    env:
+      MIX_ENV: test
+    services:
+      postgres:
+        image: "postgres:17-alpine"
+        env:
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: phoenix_sync
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 55555:5432
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: erlef/setup-beam@v1
+        with:
+          version-type: strict
+          version-file: ".tool-versions"
+
+      - name: Install dependencies
+        run: mix deps.get
+
+      - name: Run tests on apps
+        run: mix test.apps
+
   formatting:
     name: mix format --check-formatted
     runs-on: ubuntu-latest

README.md

@@ -349,6 +349,10 @@ children = [
 ]
 ```
 
+## Testing
+
+See `Phoenix.Sync.Sandbox` for details on how to test sync endpoints (liveview, controllers and routers) in your Phoenix/Ecto application.
+
 ## Notes
 
 ### ElectricSQL

apps/phoenix_sync_example/.formatter.exs

@@ -0,0 +1,6 @@
+[
+  import_deps: [:ecto, :ecto_sql, :phoenix],
+  subdirectories: ["priv/*/migrations"],
+  plugins: [Phoenix.LiveView.HTMLFormatter],
+  inputs: ["*.{heex,ex,exs}", "{config,lib,test}/**/*.{heex,ex,exs}", "priv/*/seeds.exs"]
+]

apps/phoenix_sync_example/.gitignore

@@ -0,0 +1,27 @@
+# The directory Mix will write compiled artifacts to.
+_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+cover/
+
+# The directory Mix downloads your dependencies sources to.
+deps/
+
+# Where 3rd-party dependencies like ExDoc output generated docs.
+doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
+erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
+*.ez
+
+# Temporary files, for example, from tests.
+tmp/
+
+# Ignore package tarball (built via "mix hex.build").
+phoenix_sync_example-*.tar
+

apps/phoenix_sync_example/README.md

@@ -0,0 +1,3 @@
+A small Phoenix app for testing behavior of the Phoenix Sync libraryy in-situ.
+
+**Not an official example** -- see the [examples folder for those](../../examples).

apps/phoenix_sync_example/config/config.exs

@@ -0,0 +1,35 @@
+# This file is responsible for configuring your application
+# and its dependencies with the aid of the Config module.
+#
+# This configuration file is loaded before any dependency and
+# is restricted to this project.
+
+# General application configuration
+import Config
+
+config :phoenix_sync_example,
+  ecto_repos: [PhoenixSyncExample.Repo],
+  generators: [timestamp_type: :utc_datetime, binary_id: true]
+
+# Configures the endpoint
+config :phoenix_sync_example, PhoenixSyncExampleWeb.Endpoint,
+  url: [host: "localhost"],
+  adapter: Bandit.PhoenixAdapter,
+  render_errors: [
+    formats: [html: PhoenixSyncExampleWeb.ErrorHTML, json: PhoenixSyncExampleWeb.ErrorJSON],
+    layout: false
+  ],
+  pubsub_server: PhoenixSyncExample.PubSub,
+  live_view: [signing_salt: "tLgDbjrX"]
+
+# Configures Elixir's Logger
+config :logger, :console,
+  format: "$time $metadata[$level] $message\n",
+  metadata: [:request_id]
+
+# Use Jason for JSON parsing in Phoenix
+config :phoenix, :json_library, Jason
+
+# Import environment specific config. This must remain at the bottom
+# of this file so it overrides the configuration defined above.
+import_config "#{config_env()}.exs"

apps/phoenix_sync_example/config/dev.exs

@@ -0,0 +1,84 @@
+import Config
+
+# Configure your database
+config :phoenix_sync_example, PhoenixSyncExample.Repo,
+  username: "postgres",
+  password: "password",
+  hostname: "localhost",
+  database: "phoenix_sync_example_dev",
+  port: 55555,
+  stacktrace: true,
+  show_sensitive_data_on_connection_error: true,
+  pool_size: 10
+
+# For development, we disable any cache and enable
+# debugging and code reloading.
+#
+# The watchers configuration can be used to run external
+# watchers to your application. For example, we can use it
+# to bundle .js and .css sources.
+# Binding to loopback ipv4 address prevents access from other machines.
+config :phoenix_sync_example, PhoenixSyncExampleWeb.Endpoint,
+  # Change to `ip: {0, 0, 0, 0}` to allow access from other machines.
+  http: [ip: {127, 0, 0, 1}, port: 4000],
+  check_origin: false,
+  code_reloader: true,
+  debug_errors: true,
+  secret_key_base: "uBmq7NHSNLSxZJ+aqrrggr+2tIiPQh39Xe5c0G13UPk5HWbDF6e7A2EN0BlGL/qd",
+  watchers: []
+
+# ## SSL Support
+#
+# In order to use HTTPS in development, a self-signed
+# certificate can be generated by running the following
+# Mix task:
+#
+#     mix phx.gen.cert
+#
+# Run `mix help phx.gen.cert` for more information.
+#
+# The `http:` config above can be replaced with:
+#
+#     https: [
+#       port: 4001,
+#       cipher_suite: :strong,
+#       keyfile: "priv/cert/selfsigned_key.pem",
+#       certfile: "priv/cert/selfsigned.pem"
+#     ],
+#
+# If desired, both `http:` and `https:` keys can be
+# configured to run both http and https servers on
+# different ports.
+
+# Watch static and templates for browser reloading.
+config :phoenix_sync_example, PhoenixSyncExampleWeb.Endpoint,
+  live_reload: [
+    patterns: [
+      ~r"priv/static/(?!uploads/).*(js|css|png|jpeg|jpg|gif|svg)$",
+      ~r"lib/phoenix_sync_example_web/(controllers|live|components)/.*(ex|heex)$"
+    ]
+  ]
+
+# Enable dev routes for dashboard and mailbox
+config :phoenix_sync_example, dev_routes: true
+
+# Do not include metadata nor timestamps in development logs
+config :logger, :console, format: "[$level] $message\n"
+
+# Set a higher stacktrace during development. Avoid configuring such
+# in production as building large stacktraces may be expensive.
+config :phoenix, :stacktrace_depth, 20
+
+# Initialize plugs at runtime for faster development compilation
+config :phoenix, :plug_init_mode, :runtime
+
+config :phoenix_live_view,
+  # Include HEEx debug annotations as HTML comments in rendered markup
+  debug_heex_annotations: true,
+  # Enable helpful, but potentially expensive runtime checks
+  enable_expensive_runtime_checks: true
+
+config :phoenix_sync,
+  env: config_env(),
+  repo: PhoenixSyncExample.Repo,
+  mode: :embedded

apps/phoenix_sync_example/config/prod.exs

@@ -0,0 +1,7 @@
+import Config
+
+# Do not print debug messages in production
+config :logger, level: :info
+
+# Runtime production configuration, including reading
+# of environment variables, is done on config/runtime.exs.

apps/phoenix_sync_example/config/runtime.exs

@@ -0,0 +1,99 @@
+import Config
+
+# config/runtime.exs is executed for all environments, including
+# during releases. It is executed after compilation and before the
+# system starts, so it is typically used to load production configuration
+# and secrets from environment variables or elsewhere. Do not define
+# any compile-time configuration in here, as it won't be applied.
+# The block below contains prod specific runtime configuration.
+
+# ## Using releases
+#
+# If you use `mix release`, you need to explicitly enable the server
+# by passing the PHX_SERVER=true when you start it:
+#
+#     PHX_SERVER=true bin/phoenix_sync_example start
+#
+# Alternatively, you can use `mix phx.gen.release` to generate a `bin/server`
+# script that automatically sets the env var above.
+if System.get_env("PHX_SERVER") do
+  config :phoenix_sync_example, PhoenixSyncExampleWeb.Endpoint, server: true
+end
+
+if config_env() == :prod do
+  database_url =
+    System.get_env("DATABASE_URL") ||
+      raise """
+      environment variable DATABASE_URL is missing.
+      For example: ecto://USER:PASS@HOST/DATABASE
+      """
+
+  maybe_ipv6 = if System.get_env("ECTO_IPV6") in ~w(true 1), do: [:inet6], else: []
+
+  config :phoenix_sync_example, PhoenixSyncExample.Repo,
+    # ssl: true,
+    url: database_url,
+    pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10"),
+    socket_options: maybe_ipv6
+
+  # The secret key base is used to sign/encrypt cookies and other secrets.
+  # A default value is used in config/dev.exs and config/test.exs but you
+  # want to use a different value for prod and you most likely don't want
+  # to check this value into version control, so we use an environment
+  # variable instead.
+  secret_key_base =
+    System.get_env("SECRET_KEY_BASE") ||
+      raise """
+      environment variable SECRET_KEY_BASE is missing.
+      You can generate one by calling: mix phx.gen.secret
+      """
+
+  host = System.get_env("PHX_HOST") || "example.com"
+  port = String.to_integer(System.get_env("PORT") || "4000")
+
+  config :phoenix_sync_example, :dns_cluster_query, System.get_env("DNS_CLUSTER_QUERY")
+
+  config :phoenix_sync_example, PhoenixSyncExampleWeb.Endpoint,
+    url: [host: host, port: 443, scheme: "https"],
+    http: [
+      # Enable IPv6 and bind on all interfaces.
+      # Set it to  {0, 0, 0, 0, 0, 0, 0, 1} for local network only access.
+      # See the documentation on https://hexdocs.pm/bandit/Bandit.html#t:options/0
+      # for details about using IPv6 vs IPv4 and loopback vs public addresses.
+      ip: {0, 0, 0, 0, 0, 0, 0, 0},
+      port: port
+    ],
+    secret_key_base: secret_key_base
+
+  # ## SSL Support
+  #
+  # To get SSL working, you will need to add the `https` key
+  # to your endpoint configuration:
+  #
+  #     config :phoenix_sync_example, PhoenixSyncExampleWeb.Endpoint,
+  #       https: [
+  #         ...,
+  #         port: 443,
+  #         cipher_suite: :strong,
+  #         keyfile: System.get_env("SOME_APP_SSL_KEY_PATH"),
+  #         certfile: System.get_env("SOME_APP_SSL_CERT_PATH")
+  #       ]
+  #
+  # The `cipher_suite` is set to `:strong` to support only the
+  # latest and more secure SSL ciphers. This means old browsers
+  # and clients may not be supported. You can set it to
+  # `:compatible` for wider support.
+  #
+  # `:keyfile` and `:certfile` expect an absolute path to the key
+  # and cert in disk or a relative path inside priv, for example
+  # "priv/ssl/server.key". For all supported SSL configuration
+  # options, see https://hexdocs.pm/plug/Plug.SSL.html#configure/1
+  #
+  # We also recommend setting `force_ssl` in your config/prod.exs,
+  # ensuring no data is ever sent via http, always redirecting to https:
+  #
+  #     config :phoenix_sync_example, PhoenixSyncExampleWeb.Endpoint,
+  #       force_ssl: [hsts: true]
+  #
+  # Check `Plug.SSL` for all available options in `force_ssl`.
+end

apps/phoenix_sync_example/config/test.exs

@@ -0,0 +1,36 @@
+import Config
+
+# Configure your database
+#
+# The MIX_TEST_PARTITION environment variable can be used
+# to provide built-in test partitioning in CI environment.
+# Run `mix help test` for more information.
+config :phoenix_sync_example, PhoenixSyncExample.Repo,
+  username: "postgres",
+  password: "password",
+  hostname: "localhost",
+  database: "phoenix_sync_example_test#{System.get_env("MIX_TEST_PARTITION")}",
+  port: 55555,
+  pool: Ecto.Adapters.SQL.Sandbox,
+  pool_size: System.schedulers_online() * 2
+
+# We don't run a server during test. If one is required,
+# you can enable the server option below.
+config :phoenix_sync_example, PhoenixSyncExampleWeb.Endpoint,
+  http: [ip: {127, 0, 0, 1}, port: 4002],
+  secret_key_base: "JxgUv3Dd0aEmBGFLgfyPpQPTidmD3BaW9NYtWDCnk0Yo3EaPDQgUNyLOXkm3+//h",
+  server: false
+
+# Print only warnings and errors during test
+config :logger, level: :warning
+
+# Initialize plugs at runtime for faster test compilation
+config :phoenix, :plug_init_mode, :runtime
+
+# Enable helpful, but potentially expensive runtime checks
+config :phoenix_live_view,
+  enable_expensive_runtime_checks: true
+
+config :phoenix_sync,
+  env: config_env(),
+  mode: :sandbox