Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

test: port local e2e orchestration to xtask (#4957)

teo0ab77be76d83
diff --git a/apps/web/README.md b/apps/web/README.md
index 4acc6b41df..745940dcfc 100644
--- a/apps/web/README.md
+++ b/apps/web/README.md
@@ -12,8 +12,7 @@ If you have the [nix](https://nixos.org/learn/) package manager installed on you
`nix develop`
-## Using Claude/Playwright
-To setup the authentication please make sure you create a `.env` file with **REFRESH_TOKEN** environment variable set to your dev macro refresh token. This can be found in your cookies.
+## Local Playwright
For the local smoke suite, prefer the repo-level harness:
@@ -21,7 +20,14 @@ For the local smoke suite, prefer the repo-level harness:
just local-e2e
```
-This starts the backend with local E2E compose overrides, seeds local fixture data, and runs `bun run local:e2e` with local bearer-token auth.
+This starts a named headless stack through the same xtask orchestration as
+`just run_local`, seeds local fixture data into that isolated instance, and
+runs Playwright against a Vite server connected to the instance proxy. The
+harness generates local bearer-token auth from the stack's generated env; it
+does not need a refresh token or the legacy local-E2E compose overlay.
+
+Set `LOCAL_E2E_INSTANCE` to reuse a different named stack. The default is
+`local-e2e`.
The local smoke suite can import `localE2ESeed` from `tests/e2e/fixtures/local-e2e-seed.ts`. That helper loads the actual seed files used by `seed_cli` (`local_e2e/users.json`, `documents.json`, `channels.json`, and `channel_messages.json`) and exposes raw rows plus lookup maps by id/name/email. The small `local_e2e/manifest.json` only names the smoke aliases.
diff --git a/apps/web/playwright.config.ts b/apps/web/playwright.config.ts
index 39380c2e45..2e45ed6b5d 100644
--- a/apps/web/playwright.config.ts
+++ b/apps/web/playwright.config.ts
@@ -3,7 +3,11 @@ import { execFileSync } from 'node:child_process';
import { defineConfig, devices } from '@playwright/test';
const isLocalE2E = process.env.LOCAL_E2E === 'true';
-const localE2EPort = process.env.PORT ?? '3000';
+const localE2EBaseURL = process.env.LOCAL_E2E_BASE_URL;
+const localE2EPort = localE2EBaseURL
+ ? new URL(localE2EBaseURL).port
+ : (process.env.PORT ?? '3000');
+const localE2EBackendOrigin = process.env.LOCAL_E2E_BACKEND_ORIGIN;
function shellQuote(value: string): string {
return `'${value.replaceAll("'", "'\\''")}'`;
@@ -34,8 +38,7 @@ function localE2EToken(): string {
const details = commandOutput(error);
const message = [
'Failed to generate LOCAL_JWT for LOCAL_E2E Playwright.',
- 'Prefer running the repo-level harness: `just local-e2e`.',
- 'If you are running Playwright directly, run `just local-e2e-seed` first and ensure `.env` exists from `just get_environment`.',
+ 'Run Playwright through the repo-level harness: `just local-e2e`.',
'You can also bypass token generation by exporting LOCAL_JWT.',
details ? `Generator output:\n${details}` : undefined,
]
@@ -48,9 +51,16 @@ function localE2EToken(): string {
}
function localE2EWebServerCommand(): string {
+ if (!localE2EBackendOrigin) {
+ throw new Error(
+ 'LOCAL_E2E_BACKEND_ORIGIN is required. Run Playwright through `just local-e2e`.'
+ );
+ }
+
return [
`PORT=${shellQuote(localE2EPort)}`,
'VITE_LOCAL_SERVERS=ALL',
+ `VITE_LOCAL_BACKEND_ORIGIN=${shellQuote(localE2EBackendOrigin)}`,
'VITE_ENABLE_BEARER_TOKEN_AUTH=true',
`LOCAL_JWT=${shellQuote(localE2EToken())}`,
'bun run dev',
@@ -139,7 +149,7 @@ export default defineConfig({
/* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
use: {
/* Base URL to use in actions like `await page.goto('/')`. */
- baseURL: `http://localhost:${localE2EPort}/app`,
+ baseURL: localE2EBaseURL ?? `http://localhost:${localE2EPort}/app`,
/* Only retain traces on the failed test. See https://playwright.dev/docs/trace-viewer */
trace: 'retain-on-failure',
},
diff --git a/apps/web/tests/e2e/local-smoke.spec.ts b/apps/web/tests/e2e/local-smoke.spec.ts
index 7d44905a25..e71518c3b6 100644
--- a/apps/web/tests/e2e/local-smoke.spec.ts
+++ b/apps/web/tests/e2e/local-smoke.spec.ts
@@ -60,7 +60,7 @@ test.describe('local app smoke', () => {
`/channel/${SEEDED.channel.id}?channel_message_id=${SEEDED.channel.messageId}`
);
await expect(
- page.getByText(SEEDED.channel.name, { exact: true })
+ page.getByText(SEEDED.channel.name, { exact: true }).last()
).toBeVisible();
await expect(page.getByText(SEEDED.channel.message)).toBeVisible({
timeout: 30_000,
diff --git a/crates/integration_tests/local_e2e/README.md b/crates/integration_tests/local_e2e/README.md
index 1d13118e82..25f1308c4b 100644
--- a/crates/integration_tests/local_e2e/README.md
+++ b/crates/integration_tests/local_e2e/README.md
@@ -7,5 +7,7 @@ just local-e2e-rust
```
The tests are `#[ignore]` so normal workspace test runs do not require Docker
-services. They load fixtures through `local_e2e_test_support`, which reads the
-same seed files used by `seed_cli` and Playwright.
+services. The command starts an isolated named stack through the xtask local
+orchestrator, seeds it, and supplies its generated env and proxy URLs to
+`local_e2e_test_support`. The fixtures are the same files used by `seed_cli`
+and Playwright.
diff --git a/crates/integration_tests/local_e2e/tests/channel_mutations.rs b/crates/integration_tests/local_e2e/tests/channel_mutations.rs
index 24226455a4..26a5dd30df 100644
--- a/crates/integration_tests/local_e2e/tests/channel_mutations.rs
+++ b/crates/integration_tests/local_e2e/tests/channel_mutations.rs
@@ -353,7 +353,7 @@ async fn create_public_contract_channel(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus document_storage_service"]
+#[ignore = "requires `just local-e2e-rust` plus document_storage_service"]
async fn get_or_create_dm_returns_existing_dm_and_rejects_self_dm() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_get_or_create_dm_access_control_contract(&ctx).await
@@ -397,7 +397,7 @@ async fn assert_get_or_create_dm_access_control_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus document_storage_service"]
+#[ignore = "requires `just local-e2e-rust` plus document_storage_service"]
async fn get_or_create_private_persists_expected_participants() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_get_or_create_private_access_control_contract(&ctx).await
@@ -435,7 +435,7 @@ async fn assert_get_or_create_private_access_control_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus document_storage_service"]
+#[ignore = "requires `just local-e2e-rust` plus document_storage_service"]
async fn public_channel_allows_join_and_leave_for_non_participant() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_public_join_leave_access_control_contract(&ctx).await
@@ -491,7 +491,7 @@ async fn assert_public_join_leave_access_control_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus document_storage_service and contacts_service workers"]
+#[ignore = "requires `just local-e2e-rust` plus document_storage_service and contacts_service workers"]
async fn create_private_channel_persists_channel_participants_and_contacts() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_private_channel_create_side_effect_contract(&ctx).await
@@ -530,7 +530,7 @@ async fn assert_private_channel_create_side_effect_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus document_storage_service, contacts_service, and notification_service workers"]
+#[ignore = "requires `just local-e2e-rust` plus document_storage_service, contacts_service, and notification_service workers"]
async fn adding_and_removing_participant_updates_membership_notifications_and_contacts()
-> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
@@ -592,7 +592,7 @@ async fn assert_participant_invite_remove_side_effect_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus document_storage_service and contacts_service workers"]
+#[ignore = "requires `just local-e2e-rust` plus document_storage_service and contacts_service workers"]
async fn public_join_and_leave_updates_membership_and_contacts() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_public_join_leave_side_effect_contract(&ctx).await
@@ -643,7 +643,7 @@ async fn assert_public_join_leave_side_effect_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus document_storage_service"]
+#[ignore = "requires `just local-e2e-rust` plus document_storage_service"]
async fn delete_channel_removes_channel() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_channel_delete_side_effect_contract(&ctx).await
@@ -666,7 +666,7 @@ async fn assert_channel_delete_side_effect_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus document_storage_service"]
+#[ignore = "requires `just local-e2e-rust` plus document_storage_service"]
async fn channel_rename_persists_name() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_channel_rename_side_effect_contract(&ctx).await
@@ -691,7 +691,7 @@ async fn assert_channel_rename_side_effect_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus connection_gateway, document_storage_service, and notification_service workers"]
+#[ignore = "requires `just local-e2e-rust` plus connection_gateway, document_storage_service, and notification_service workers"]
async fn message_with_document_attachment_updates_channel_share_permissions_and_side_effects()
-> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
@@ -821,7 +821,7 @@ async fn assert_document_attachment_share_permission_side_effect_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus connection_gateway, document_storage_service, and notification_service workers"]
+#[ignore = "requires `just local-e2e-rust` plus connection_gateway, document_storage_service, and notification_service workers"]
async fn follow_up_message_persists_message_emits_realtime_and_sends_notifications()
-> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
@@ -918,7 +918,7 @@ async fn assert_follow_up_message_side_effect_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus connection_gateway and document_storage_service"]
+#[ignore = "requires `just local-e2e-rust` plus connection_gateway and document_storage_service"]
async fn typing_emits_realtime() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_typing_side_effect_contract(&ctx).await
@@ -967,7 +967,7 @@ async fn assert_typing_side_effect_contract(ctx: &ChannelContractContext) -> any
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus connection_gateway and document_storage_service"]
+#[ignore = "requires `just local-e2e-rust` plus connection_gateway and document_storage_service"]
async fn reaction_persists_reaction_and_emits_realtime() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_reaction_side_effect_contract(&ctx).await
@@ -1034,7 +1034,7 @@ async fn assert_reaction_side_effect_contract(ctx: &ChannelContractContext) -> a
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus connection_gateway, document_storage_service, and notification_service workers"]
+#[ignore = "requires `just local-e2e-rust` plus connection_gateway, document_storage_service, and notification_service workers"]
async fn thread_reply_persists_thread_id_emits_realtime_and_notifies_parent_author()
-> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
@@ -1129,7 +1129,7 @@ async fn assert_thread_reply_side_effect_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus connection_gateway and document_storage_service"]
+#[ignore = "requires `just local-e2e-rust` plus connection_gateway and document_storage_service"]
async fn message_edit_persists_content_and_emits_realtime() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_message_edit_side_effect_contract(&ctx).await
@@ -1203,7 +1203,7 @@ async fn assert_message_edit_side_effect_contract(
}
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus connection_gateway and document_storage_service"]
+#[ignore = "requires `just local-e2e-rust` plus connection_gateway and document_storage_service"]
async fn message_delete_persists_tombstone_and_emits_realtime() -> anyhow::Result<()> {
let ctx = ChannelContractContext::load().await?;
assert_message_delete_side_effect_contract(&ctx).await
diff --git a/crates/integration_tests/local_e2e/tests/channel_websocket.rs b/crates/integration_tests/local_e2e/tests/channel_websocket.rs
index 666fa639a1..fb9889c481 100644
--- a/crates/integration_tests/local_e2e/tests/channel_websocket.rs
+++ b/crates/integration_tests/local_e2e/tests/channel_websocket.rs
@@ -14,7 +14,7 @@ use tokio_tungstenite::tungstenite::{Error as WebsocketError, Message as Websock
const WEBSOCKET_TIMEOUT: Duration = Duration::from_secs(10);
#[tokio::test]
-#[ignore = "requires `just local-e2e-seed` plus connection_gateway and document_storage_service"]
+#[ignore = "requires `just local-e2e-rust` plus connection_gateway and document_storage_service"]
async fn channel_message_posts_to_http_and_delivers_to_websocket() -> anyhow::Result<()> {
let config = LocalE2eConfig::load()?;
let seed = LocalE2eSeed::from_config(&config)?;
diff --git a/crates/local_e2e_test_support/README.md b/crates/local_e2e_test_support/README.md
index 680c069bfe..1e0490deeb 100644
--- a/crates/local_e2e_test_support/README.md
+++ b/crates/local_e2e_test_support/README.md
@@ -3,10 +3,12 @@
Shared Rust helpers for local E2E tests.
- Loads fixture data from `tooling/seed_cli/seed`.
-- Generates local Macro API JWTs from `.env` / process env.
+- Generates local Macro API JWTs from the xtask instance env selected by
+ `LOCAL_E2E_ENV_FILE`, falling back to `.env`, with process env overrides.
- Provides standard local service URLs for the `run_local` stack.
- Refuses non-local service URLs so tests do not mutate shared dev services.
Use this crate from ignored integration tests that are run by `just local-e2e-rust`.
+That harness starts and seeds an isolated named stack before running the tests.
Override service URLs only with local endpoints via `LOCAL_E2E_DOCUMENT_STORAGE_URL`
or `LOCAL_E2E_CONNECTION_GATEWAY_WS_URL`.
diff --git a/crates/local_e2e_test_support/src/config.rs b/crates/local_e2e_test_support/src/config.rs
index 5068835b5c..6017e3fc8a 100644
--- a/crates/local_e2e_test_support/src/config.rs
+++ b/crates/local_e2e_test_support/src/config.rs
@@ -6,9 +6,10 @@ use std::{
use anyhow::Context;
const SEED_DIR_MARKER: &str = "tooling/seed_cli/seed";
+const ENV_FILE_OVERRIDE: &str = "LOCAL_E2E_ENV_FILE";
-/// Local E2E runtime configuration loaded from the repository `.env` plus the
-/// process environment.
+/// Local E2E runtime configuration loaded from the selected dotenv file plus
+/// the process environment.
#[derive(Clone, Debug)]
pub struct LocalE2eConfig {
repo_root: PathBuf,
@@ -26,8 +27,17 @@ impl LocalE2eConfig {
/// Load configuration using an explicit repository root.
pub fn from_repo_root(repo_root: PathBuf) -> anyhow::Result<Self> {
+ let dotenv_path = std::env::var_os(ENV_FILE_OVERRIDE)
+ .map(PathBuf::from)
+ .unwrap_or_else(|| repo_root.join(".env"));
+ Self::from_repo_root_and_env_file(repo_root, dotenv_path)
+ }
+
+ fn from_repo_root_and_env_file(
+ repo_root: PathBuf,
+ dotenv_path: PathBuf,
+ ) -> anyhow::Result<Self> {
let mut values = HashMap::new();
- let dotenv_path = repo_root.join(".env");
if dotenv_path.exists() {
for item in dotenvy::from_path_iter(&dotenv_path)
@@ -74,3 +84,6 @@ fn find_repo_root() -> anyhow::Result<PathBuf> {
.map(Path::to_path_buf)
.context("CARGO_MANIFEST_DIR must be under crates/<crate>")
}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/local_e2e_test_support/src/config/test.rs b/crates/local_e2e_test_support/src/config/test.rs
new file mode 100644
index 0000000000..5ceff3727f
--- /dev/null
+++ b/crates/local_e2e_test_support/src/config/test.rs
@@ -0,0 +1,19 @@
+use std::path::PathBuf;
+
+use super::LocalE2eConfig;
+
+#[test]
+fn explicit_environment_file_is_loaded() {
+ let env_file = std::env::temp_dir().join(format!(
+ "macro-local-e2e-config-test-{}.env",
+ std::process::id()
+ ));
+ std::fs::write(&env_file, "LOCAL_E2E_CONFIG_TEST=instance\n").unwrap();
+
+ let config =
+ LocalE2eConfig::from_repo_root_and_env_file(PathBuf::from("/unused"), env_file.clone())
+ .unwrap();
+ std::fs::remove_file(env_file).unwrap();
+
+ assert_eq!(config.get("LOCAL_E2E_CONFIG_TEST"), Some("instance"));
+}
diff --git a/crates/macro_queues/src/lib.rs b/crates/macro_queues/src/lib.rs
index d5c7e2b85e..fb492e55a0 100644
--- a/crates/macro_queues/src/lib.rs
+++ b/crates/macro_queues/src/lib.rs
@@ -447,7 +447,7 @@ queue! {
/// Common SQS queues used by Macro services.
///
/// Default values mirror what infrastructure provisions: `local` uses the
- /// bare queue names seen in `docker/docker-compose.local-e2e.yml`, while `dev` and
+ /// bare queue names emitted by the xtask local environment, while `dev` and
/// `prod` use the `{base}-queue-{stack}` names provisioned by Pulumi.
pub struct Queues {
/// Queue for document text extraction jobs.
diff --git a/crates/webhook/README.md b/crates/webhook/README.md
index dc549290af..53dfff03d7 100644
--- a/crates/webhook/README.md
+++ b/crates/webhook/README.md
@@ -211,9 +211,9 @@ just run_local --no-frontend
```
Services inside the local compose network receive
-`http://localstack:4566/000000000000/webhook-event-queue.fifo`. The
-`docker/docker-compose.local-e2e.yml` environment supplies the same override. Worker
-polling defaults to 10 messages and a 20-second long poll and can be adjusted
+`http://localstack:4566/000000000000/webhook-event-queue.fifo`. The local E2E
+harness now receives the same override from its xtask-generated instance env.
+Worker polling defaults to 10 messages and a 20-second long poll and can be adjusted
with `WEBHOOK_QUEUE_MAX_MESSAGES` and `WEBHOOK_QUEUE_WAIT_TIME_SECONDS`.
### Tracing
diff --git a/justfile b/justfile
index e04f20cbb8..d5c06b6c6f 100644
--- a/justfile
+++ b/justfile
@@ -44,17 +44,6 @@ docker_up *ARGS:
echo "startup docker compose"
{{ compose }} up {{ ARGS }}
-# Reset and seed deterministic data used by local E2E tests.
-local-e2e-seed:
- just run_dbs -d
- -just crates/macro_db_client/drop_db -y -f
- just initialize_dbs
- just tooling/seed_cli/local-e2e-smoke
-
-# Start only the services needed by the local E2E suites. Avoid unrelated
-# local services with extra env/dependency requirements blocking E2E.
-local-e2e-services := "authentication-service connection_gateway contacts_service document_storage_service email_service notification_service static_file_service static_file_cdn sync_service websocket_service"
-
# Update the fixed-output js node_modules hash after bun.lock changes.
update-node-modules-hash:
tooling/scripts/update-node-modules-hash.sh
@@ -63,35 +52,6 @@ update-node-modules-hash:
check-node-modules-nix:
nix build .#js-node-modules --no-link
-# Start the local stack, seed deterministic data, and run the Playwright smoke suite.
-local-e2e *ARGS:
- AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 just setup_localstack
- COMPOSE_FILE=docker/docker-compose.yml:docker/docker-compose.local-e2e.yml bash tooling/scripts/run-local.sh -d --wait {{ local-e2e-services }}
- just local-e2e-seed
- cd apps/web && LOCAL_E2E=true bunx playwright test {{ ARGS }}
-
-# Start the local stack, seed deterministic data, and run ignored Rust local E2E integration tests.
-local-e2e-rust *ARGS:
- AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 just setup_localstack
- COMPOSE_FILE=docker/docker-compose.yml:docker/docker-compose.local-e2e.yml bash tooling/scripts/run-local.sh -d --wait {{ local-e2e-services }}
- just local-e2e-seed
- SQLX_OFFLINE=true cargo test -p local_e2e_integration_tests -- --ignored --nocapture {{ ARGS }}
-
-# Start the local stack once, seed deterministic data, and run Rust + Playwright local E2E tests.
-local-e2e-all *ARGS:
- AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 just setup_localstack
- COMPOSE_FILE=docker/docker-compose.yml:docker/docker-compose.local-e2e.yml bash tooling/scripts/run-local.sh -d --wait {{ local-e2e-services }}
- just local-e2e-seed
- SQLX_OFFLINE=true cargo test -p local_e2e_integration_tests -- --ignored --nocapture
- cd apps/web && LOCAL_E2E=true bunx playwright test {{ ARGS }}
-
-# Start the local stack, seed deterministic data, and open Playwright UI mode.
-local-e2e-ui *ARGS:
- AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 just setup_localstack
- COMPOSE_FILE=docker/docker-compose.yml:docker/docker-compose.local-e2e.yml bash tooling/scripts/run-local.sh -d --wait {{ local-e2e-services }}
- just local-e2e-seed
- cd apps/web && LOCAL_E2E=true bunx playwright test --ui {{ ARGS }}
-
# Patches .env with local FusionAuth values if the Pulumi stack exists.
# Requires FusionAuth to be running — starts it temporarily if needed.
patch_local_fusionauth_env:
diff --git a/tooling/just/xtask.just b/tooling/just/xtask.just
index c1e8d91dea..18c1d6baba 100644
--- a/tooling/just/xtask.just
+++ b/tooling/just/xtask.just
@@ -39,3 +39,19 @@ stop_local *ARGS:
# just stack down # reclaim everything
stack *ARGS:
{{ xtask }} stack "$@"
+
+# Start an isolated stack, seed it, and run the local Playwright suite.
+local-e2e *ARGS:
+ tooling/scripts/run-local-e2e.sh --suite web -- "$@"
+
+# Start and seed the same isolated stack, then run ignored Rust integration tests.
+local-e2e-rust *ARGS:
+ tooling/scripts/run-local-e2e.sh --suite rust -- "$@"
+
+# Start and seed once, then run the Rust and Playwright suites.
+local-e2e-all *ARGS:
+ tooling/scripts/run-local-e2e.sh --suite all -- "$@"
+
+# Start and seed the stack, then open Playwright UI mode.
+local-e2e-ui *ARGS:
+ tooling/scripts/run-local-e2e.sh --suite web --ui -- "$@"
diff --git a/tooling/scripts/run-local-e2e.sh b/tooling/scripts/run-local-e2e.sh
new file mode 100755
index 0000000000..5c79de9252
--- /dev/null
+++ b/tooling/scripts/run-local-e2e.sh
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(\cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+# The local stack cross-compiles bundled C/C++ dependencies. The repository's
+# Nix shell supplies the matching Zig/cargo-zigbuild pair and target headers;
+# this wrapper only enters that shell. Xtask owns the E2E lifecycle itself.
+if [[ -z "${IN_NIX_SHELL:-}" ]]; then
+ if [[ "${LOCAL_E2E_NIX_REEXEC:-}" == "1" ]]; then
+ echo "local E2E failed to enter the repository Nix development shell" >&2
+ exit 1
+ fi
+ if ! command -v nix >/dev/null 2>&1; then
+ echo "local E2E requires the repository Nix development shell (nix was not found)" >&2
+ exit 1
+ fi
+ export LOCAL_E2E_NIX_REEXEC=1
+ exec nix develop "$ROOT_DIR" --command "$ROOT_DIR/tooling/scripts/run-local-e2e.sh" "$@"
+fi
+
+exec cargo run --quiet --manifest-path "$ROOT_DIR/Cargo.toml" \
+ -p xtask_local --features local-stack -- local-e2e "$@"
diff --git a/tooling/seed_cli/justfile b/tooling/seed_cli/justfile
index 95b0122d2c..d336113443 100644
--- a/tooling/seed_cli/justfile
+++ b/tooling/seed_cli/justfile
@@ -14,21 +14,3 @@ get_environment:
[positional-arguments]
seed *ARGS:
cargo r "$@"
-
-# Reset and seed deterministic data for the local Playwright smoke suite.
-local-e2e-smoke:
- LOCAL_E2E_SEED="true" \
- DATABASE_URL="postgres://user:password@localhost:5432/macrodb" \
- LOCAL_AWS_URL="http://localhost:4566" \
- DOCUMENT_STORAGE_BUCKET="doc-storage" \
- AWS_ACCESS_KEY_ID="test" \
- AWS_SECRET_ACCESS_KEY="test" \
- SQLX_OFFLINE="true" \
- ENVIRONMENT="local" \
- FUSIONAUTH_BASE_URL="http://localhost:9011" \
- FUSIONAUTH_API_KEY_SECRET_KEY="local" \
- FUSIONAUTH_TENANT_ID="local" \
- FUSIONAUTH_CLIENT_ID="local" \
- FUSIONAUTH_CLIENT_SECRET_KEY="local" \
- FUSIONAUTH_OAUTH_REDIRECT_URI="http://localhost:8080/oauth/redirect" \
- cargo r -- scenario local-e2e-smoke
diff --git a/tooling/seed_cli/src/entity/scenario/mod.rs b/tooling/seed_cli/src/entity/scenario/mod.rs
index 353c68910f..b682d6fe49 100644
--- a/tooling/seed_cli/src/entity/scenario/mod.rs
+++ b/tooling/seed_cli/src/entity/scenario/mod.rs
@@ -230,14 +230,12 @@ fn validate_local_e2e_database_url(database_url: &str) -> anyhow::Result<()> {
let host = parsed.host_str().unwrap_or_default();
let username = parsed.username();
let database = parsed.path().trim_start_matches('/');
- let port = parsed.port_or_known_default();
-
let is_local_host = matches!(host, "localhost" | "127.0.0.1" | "::1" | "postgres");
- let is_local_compose_db = username == "user" && database == "macrodb" && port == Some(5432);
+ let is_local_compose_db = username == "user" && database == "macrodb";
ensure!(
is_local_host && is_local_compose_db,
- "refusing to run local-e2e-smoke seed against DATABASE_URL host={host:?} user={username:?} database={database:?}; expected local docker database postgres://user:...@(localhost|127.0.0.1|postgres):5432/macrodb"
+ "refusing to run local-e2e-smoke seed against DATABASE_URL host={host:?} user={username:?} database={database:?}; expected a local database postgres://user:...@(localhost|127.0.0.1|postgres):<port>/macrodb"
);
Ok(())
@@ -250,6 +248,8 @@ mod tests {
#[test]
fn local_e2e_database_url_accepts_localhost_compose_db() {
validate_local_e2e_database_url("postgres://user:password@localhost:5432/macrodb").unwrap();
+ validate_local_e2e_database_url("postgres://user:password@localhost:31000/macrodb")
+ .unwrap();
validate_local_e2e_database_url("postgres://user:[email protected]:5432/macrodb").unwrap();
validate_local_e2e_database_url("postgres://user:password@postgres:5432/macrodb").unwrap();
}
diff --git a/tooling/xtask/crates/xtask_local/src/local/cli.rs b/tooling/xtask/crates/xtask_local/src/local/cli.rs
index 947906293e..37ab9f4a39 100644
--- a/tooling/xtask/crates/xtask_local/src/local/cli.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/cli.rs
@@ -42,6 +42,8 @@ enum Cmd {
ResetLocal(InstanceArgs),
/// Remove an instance's containers, networks, and volumes.
DestroyLocal(InstanceArgs),
+ /// Start, seed, and test an isolated local E2E stack.
+ LocalE2e(super::e2e::LocalE2eArgs),
/// Headless stack orchestration (previews, agents, CI) — no TTY, no
/// attached dev server; the proxy serves a static frontend bundle.
#[command(subcommand)]
@@ -177,8 +179,9 @@ fn run(cli: Cli) -> Result<()> {
Cmd::StopLocal(a) => super::stop(&a),
Cmd::ResetLocal(a) => super::reset(&a),
Cmd::DestroyLocal(a) => super::destroy(&a),
+ Cmd::LocalE2e(a) => super::e2e::run(&a),
Cmd::Stack(cmd) => match cmd {
- StackCmd::Up(a) => super::stack::up(Mode::Local, &a),
+ StackCmd::Up(a) => super::stack::up(Mode::Local, &a).map(|_| ()),
StackCmd::Update(a) => super::stack::update(&a),
StackCmd::Status(a) => super::stack::status(&a),
StackCmd::Down(a) => super::stack::down(&a),
@@ -186,3 +189,6 @@ fn run(cli: Cli) -> Result<()> {
},
}
}
+
+#[cfg(test)]
+mod test;
diff --git a/tooling/xtask/crates/xtask_local/src/local/cli/test.rs b/tooling/xtask/crates/xtask_local/src/local/cli/test.rs
new file mode 100644
index 0000000000..a0049258d4
--- /dev/null
+++ b/tooling/xtask/crates/xtask_local/src/local/cli/test.rs
@@ -0,0 +1,26 @@
+use super::*;
+use crate::local::e2e::LocalE2eSuite;
+
+#[test]
+fn local_e2e_accepts_suite_and_trailing_test_arguments() {
+ let cli = Cli::try_parse_from([
+ "cargo-x",
+ "local-e2e",
+ "--suite",
+ "web",
+ "--",
+ "tests/e2e/local-smoke.spec.ts",
+ "--grep",
+ "channels",
+ ])
+ .unwrap();
+
+ let Cmd::LocalE2e(args) = cli.command else {
+ panic!("expected local-e2e command");
+ };
+ assert_eq!(args.suite, LocalE2eSuite::Web);
+ assert_eq!(
+ args.test_args,
+ ["tests/e2e/local-smoke.spec.ts", "--grep", "channels"]
+ );
+}
diff --git a/tooling/xtask/crates/xtask_local/src/local/e2e.rs b/tooling/xtask/crates/xtask_local/src/local/e2e.rs
new file mode 100644
index 0000000000..0f9118a0a4
--- /dev/null
+++ b/tooling/xtask/crates/xtask_local/src/local/e2e.rs
@@ -0,0 +1,236 @@
+//! Local E2E orchestration: isolated stack, deterministic seed, and test runner.
+
+use std::collections::BTreeMap;
+use std::ffi::OsString;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use anyhow::{Context, Result, ensure};
+use clap::{Args, ValueEnum};
+
+use super::cli::{BuildArgs, EnvArgs, InstanceArgs, RunArgs};
+use super::instance::{Instance, Port};
+use super::{Mode, frontend, proxy, repo_root, stack};
+
+const DEFAULT_INSTANCE: &str = "local-e2e";
+
+/// Which local E2E suite xtask should run after seeding.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, ValueEnum)]
+pub enum LocalE2eSuite {
+ /// Run the Playwright suite.
+ #[default]
+ Web,
+ /// Run the ignored Rust integration tests.
+ Rust,
+ /// Run Rust first, then Playwright.
+ All,
+}
+
+/// Arguments for `cargo x local-e2e`.
+#[derive(Args, Clone, Debug, Default)]
+pub struct LocalE2eArgs {
+ /// Isolated stack name. Defaults to `LOCAL_E2E_INSTANCE` or `local-e2e`.
+ #[arg(long)]
+ pub instance: Option<String>,
+ /// Override the instance's derived port base.
+ #[arg(long)]
+ pub port_base: Option<u16>,
+ /// Test suite to run after the stack is ready and seeded.
+ #[arg(long, value_enum, default_value_t)]
+ pub suite: LocalE2eSuite,
+ /// Open Playwright's interactive UI instead of running headlessly.
+ #[arg(long)]
+ pub ui: bool,
+ /// Arguments forwarded to the selected suite. In `all`, they go to Playwright.
+ #[arg(last = true, allow_hyphen_values = true)]
+ pub test_args: Vec<String>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+struct Endpoints {
+ proxy_url: String,
+ frontend_url: String,
+ postgres_url: String,
+ fusionauth_url: String,
+ localstack_url: String,
+ connection_gateway_ws_url: String,
+ generated_env: PathBuf,
+}
+
+impl Endpoints {
+ fn for_instance(instance: &Instance) -> Self {
+ Self {
+ proxy_url: proxy::url(instance),
+ frontend_url: frontend::url(instance),
+ postgres_url: format!(
+ "postgres://user:password@localhost:{}/macrodb",
+ instance.port(Port::Postgres)
+ ),
+ fusionauth_url: format!("http://localhost:{}", instance.port(Port::FusionAuth)),
+ localstack_url: format!("http://localhost:{}", instance.port(Port::LocalStack)),
+ connection_gateway_ws_url: format!(
+ "ws://localhost:{}/connection-gateway",
+ instance.port(Port::Proxy)
+ ),
+ generated_env: instance.artifact_dir().join("local.generated.env"),
+ }
+ }
+
+ fn test_env(&self) -> BTreeMap<String, String> {
+ let mut env = BTreeMap::new();
+ env.insert("LOCAL_E2E".into(), "true".into());
+ env.insert(
+ "LOCAL_E2E_ENV_FILE".into(),
+ self.generated_env.display().to_string(),
+ );
+ env.insert("LOCAL_E2E_BASE_URL".into(), self.frontend_url.clone());
+ env.insert("LOCAL_E2E_BACKEND_ORIGIN".into(), self.proxy_url.clone());
+ env.insert("LOCAL_E2E_DATABASE_URL".into(), self.postgres_url.clone());
+ env.insert("DATABASE_URL".into(), self.postgres_url.clone());
+ env.insert(
+ "LOCAL_E2E_DOCUMENT_STORAGE_URL".into(),
+ format!("{}/dss", self.proxy_url),
+ );
+ env.insert(
+ "LOCAL_E2E_CONNECTION_GATEWAY_WS_URL".into(),
+ self.connection_gateway_ws_url.clone(),
+ );
+ env.insert(
+ "LOCAL_E2E_NOTIFICATION_URL".into(),
+ format!("{}/notification", self.proxy_url),
+ );
+ env
+ }
+}
+
+/// Start an isolated stack, seed it, and run the requested local E2E suite.
+pub fn run(args: &LocalE2eArgs) -> Result<()> {
+ validate_args(args)?;
+ super::kafka::ensure_available("local-e2e")?;
+
+ let instance_name = args
+ .instance
+ .clone()
+ .or_else(|| macro_env_var::maybe_read_env("LOCAL_E2E_INSTANCE"))
+ .unwrap_or_else(|| DEFAULT_INSTANCE.to_string());
+ let up_args = stack::UpArgs {
+ run: RunArgs {
+ instance: InstanceArgs {
+ instance: Some(instance_name),
+ port_base: args.port_base,
+ },
+ env: EnvArgs::default(),
+ build: BuildArgs::default(),
+ no_frontend: true,
+ verbose: false,
+ },
+ ..stack::UpArgs::default()
+ };
+ let instance = stack::up(Mode::Local, &up_args)?;
+ let endpoints = Endpoints::for_instance(&instance);
+ ensure!(
+ endpoints.generated_env.is_file(),
+ "generated stack environment not found at {}",
+ endpoints.generated_env.display()
+ );
+
+ run_seed(&endpoints)?;
+ let test_env = endpoints.test_env();
+ match args.suite {
+ LocalE2eSuite::Web => run_web(&test_env, args.ui, &args.test_args),
+ LocalE2eSuite::Rust => run_rust(&test_env, &args.test_args),
+ LocalE2eSuite::All => {
+ run_rust(&test_env, &[])?;
+ run_web(&test_env, false, &args.test_args)
+ }
+ }
+}
+
+fn validate_args(args: &LocalE2eArgs) -> Result<()> {
+ ensure!(
+ !args.ui || args.suite == LocalE2eSuite::Web,
+ "--ui is only supported with --suite web"
+ );
+ Ok(())
+}
+
+fn run_seed(endpoints: &Endpoints) -> Result<()> {
+ println!("\nSeeding local E2E fixtures...");
+ let mut env = load_generated_env(&endpoints.generated_env)?;
+ env.insert("LOCAL_E2E_SEED".into(), "true".into());
+ env.insert("DATABASE_URL".into(), endpoints.postgres_url.clone());
+ env.insert("LOCAL_AWS_URL".into(), endpoints.localstack_url.clone());
+ env.insert(
+ "FUSIONAUTH_BASE_URL".into(),
+ endpoints.fusionauth_url.clone(),
+ );
+ env.insert(
+ "FUSIONAUTH_OAUTH_REDIRECT_URI".into(),
+ endpoints.frontend_url.clone(),
+ );
+
+ let mut command = cargo_command();
+ command
+ .current_dir(repo_root())
+ .args(["run", "--quiet", "--manifest-path"])
+ .arg(repo_root().join("Cargo.toml"))
+ .args(["-p", "seed_cli", "--", "scenario", "local-e2e-smoke"])
+ .envs(env)
+ .env_remove("SQLX_OFFLINE");
+ require_success(&mut command, "local E2E seed")
+}
+
+fn run_rust(env: &BTreeMap<String, String>, test_args: &[String]) -> Result<()> {
+ println!("\nRunning Rust local E2E tests...");
+ let mut command = cargo_command();
+ command
+ .current_dir(repo_root())
+ .args(["test", "--manifest-path"])
+ .arg(repo_root().join("Cargo.toml"))
+ .args([
+ "-p",
+ "local_e2e_integration_tests",
+ "--",
+ "--ignored",
+ "--nocapture",
+ ])
+ .args(test_args)
+ .envs(env)
+ .env_remove("SQLX_OFFLINE");
+ require_success(&mut command, "Rust local E2E tests")
+}
+
+fn run_web(env: &BTreeMap<String, String>, ui: bool, test_args: &[String]) -> Result<()> {
+ println!("\nRunning Playwright local E2E tests...");
+ let mut command = Command::new("bunx");
+ command
+ .current_dir(repo_root().join("apps/web"))
+ .args(["playwright", "test"]);
+ if ui {
+ command.arg("--ui");
+ }
+ command.args(test_args).envs(env);
+ require_success(&mut command, "Playwright local E2E tests")
+}
+
+fn load_generated_env(path: &Path) -> Result<BTreeMap<String, String>> {
+ dotenvy::from_path_iter(path)
+ .with_context(|| format!("reading generated stack environment {}", path.display()))?
+ .map(|entry| entry.map_err(anyhow::Error::from))
+ .collect()
+}
+
+fn cargo_command() -> Command {
+ Command::new(std::env::var_os("CARGO").unwrap_or_else(|| OsString::from("cargo")))
+}
+
+fn require_success(command: &mut Command, description: &str) -> Result<()> {
+ let status = command
+ .status()
+ .with_context(|| format!("starting {description}"))?;
+ ensure!(status.success(), "{description} exited with {status}");
+ Ok(())
+}
+
+#[cfg(test)]
+mod test;
diff --git a/tooling/xtask/crates/xtask_local/src/local/e2e/test.rs b/tooling/xtask/crates/xtask_local/src/local/e2e/test.rs
new file mode 100644
index 0000000000..7255615453
--- /dev/null
+++ b/tooling/xtask/crates/xtask_local/src/local/e2e/test.rs
@@ -0,0 +1,48 @@
+use super::*;
+
+#[test]
+fn derives_host_endpoints_and_test_environment_from_the_instance() {
+ let instance = Instance::derive(Some("e2e-test"), Some(31_000)).unwrap();
+ let endpoints = Endpoints::for_instance(&instance);
+
+ assert_eq!(endpoints.proxy_url, "http://localhost:31009");
+ assert_eq!(endpoints.frontend_url, "http://localhost:31010/app");
+ assert_eq!(
+ endpoints.postgres_url,
+ "postgres://user:password@localhost:31000/macrodb"
+ );
+ assert_eq!(endpoints.fusionauth_url, "http://localhost:31005");
+ assert_eq!(endpoints.localstack_url, "http://localhost:31006");
+ assert_eq!(
+ endpoints.connection_gateway_ws_url,
+ "ws://localhost:31009/connection-gateway"
+ );
+
+ let env = endpoints.test_env();
+ assert_eq!(env["LOCAL_E2E_BACKEND_ORIGIN"], endpoints.proxy_url);
+ assert_eq!(
+ env["LOCAL_E2E_CONNECTION_GATEWAY_WS_URL"],
+ "ws://localhost:31009/connection-gateway"
+ );
+ assert_eq!(env["DATABASE_URL"], endpoints.postgres_url);
+ assert_eq!(
+ env["LOCAL_E2E_ENV_FILE"],
+ endpoints.generated_env.display().to_string()
+ );
+}
+
+#[test]
+fn ui_requires_the_web_suite() {
+ let args = LocalE2eArgs {
+ suite: LocalE2eSuite::Rust,
+ ui: true,
+ ..LocalE2eArgs::default()
+ };
+
+ let error = validate_args(&args).unwrap_err();
+ assert!(
+ error
+ .to_string()
+ .contains("only supported with --suite web")
+ );
+}
diff --git a/tooling/xtask/crates/xtask_local/src/local/mod.rs b/tooling/xtask/crates/xtask_local/src/local/mod.rs
index e42d0bd0ce..43f091808c 100644
--- a/tooling/xtask/crates/xtask_local/src/local/mod.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/mod.rs
@@ -19,6 +19,7 @@ pub mod cli;
pub mod db;
pub mod docker;
pub mod doctor;
+pub mod e2e;
pub mod env_layer;
pub mod frontend;
pub mod fusionauth;
diff --git a/tooling/xtask/crates/xtask_local/src/local/stack.rs b/tooling/xtask/crates/xtask_local/src/local/stack.rs
index 5ad2cadf7d..f241ff95c5 100644
--- a/tooling/xtask/crates/xtask_local/src/local/stack.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/stack.rs
@@ -150,7 +150,7 @@ pub(super) fn clear_state(instance: &Instance) -> Result<()> {
/// `cargo x stack up` — bring the whole stack up and return, leaving only
/// Docker containers running.
-pub fn up(mode: Mode, args: &UpArgs) -> Result<()> {
+pub fn up(mode: Mode, args: &UpArgs) -> Result<Instance> {
let stage = Stage::from_env_cli(args.run.verbose);
let instance = Instance::derive(
args.run.instance.instance.as_deref(),
@@ -252,7 +252,7 @@ pub fn up(mode: Mode, args: &UpArgs) -> Result<()> {
serde_json::to_string(&summary_json(mode, &instance, false))?
);
}
- return Ok(());
+ return Ok(instance);
}
super::bring_up_app(&stage, mode, &instance, &env)?;
@@ -294,7 +294,7 @@ pub fn up(mode: Mode, args: &UpArgs) -> Result<()> {
serde_json::to_string(&summary_json(mode, &instance, static_frontend))?
);
}
- Ok(())
+ Ok(instance)
}
/// `cargo x stack update` — the `r` hotkey as a one-shot verb: rebuild the