Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Add mobile app e2e test scaffolding (#1404)

Leendert de Borst426618ab9028
diff --git a/apps/mobile-app/.gitignore b/apps/mobile-app/.gitignore
index 6d26df642..d8472a4d5 100644
--- a/apps/mobile-app/.gitignore
+++ b/apps/mobile-app/.gitignore
@@ -47,3 +47,8 @@ app-example
# Test output files
coverage
build
+
+# Maestro E2E test outputs
+.maestro/tests/
+maestro-report.xml
+*.png
diff --git a/apps/mobile-app/.maestro/config.yaml b/apps/mobile-app/.maestro/config.yaml
new file mode 100644
index 000000000..e16641cb3
--- /dev/null
+++ b/apps/mobile-app/.maestro/config.yaml
@@ -0,0 +1,30 @@
+# Maestro E2E Test Configuration
+# https://maestro.dev/docs/configuration
+
+# Application identifiers
+appId: net.aliasvault.app
+
+# Default timeout for assertions (ms)
+defaultTimeout: 10000
+
+# Environment variables (can be overridden via CLI)
+env:
+ # API server URL for testing
+ API_URL: "http://localhost:5092"
+
+ # Test user credentials (set via CI secrets or local .env)
+ TEST_USERNAME: ""
+ TEST_PASSWORD: ""
+
+# Test configuration
+flows:
+ # Run flows in order (numbered prefixes ensure correct sequence)
+ - ".maestro/flows/"
+
+# Screenshots configuration
+screenshots:
+ enabled: true
+ format: png
+
+# Logging
+logLevel: info
diff --git a/apps/mobile-app/.maestro/flows/01-app-launch.yaml b/apps/mobile-app/.maestro/flows/01-app-launch.yaml
new file mode 100644
index 000000000..93e6485ff
--- /dev/null
+++ b/apps/mobile-app/.maestro/flows/01-app-launch.yaml
@@ -0,0 +1,37 @@
+# Test 01: App Launch
+# Verifies the app launches correctly and shows the login screen
+#
+# Prerequisites: None (first test in sequence)
+# Expected: App launches and displays login form
+
+appId: net.aliasvault.app
+---
+# Launch the app with a clean state
+- launchApp:
+ clearState: true
+
+# Wait for app to fully load - look for AliasVault text
+- extendedWaitUntil:
+ visible: "AliasVault"
+ timeout: 15000
+
+# Verify the login screen is displayed (use testID or fall back to text)
+- assertVisible:
+ id: "login-screen"
+ optional: true
+
+# Verify login form elements - try testID first, then text placeholder
+- assertVisible:
+ id: "username-input"
+ optional: true
+
+- assertVisible:
+ id: "password-input"
+ optional: true
+
+# Check for Log in button using text (note: "Log in" with space)
+- assertVisible:
+ text: "Log in"
+
+# Take screenshot of successful launch
+- takeScreenshot: "01-app-launched"
diff --git a/apps/mobile-app/.maestro/flows/02-login-validation.yaml b/apps/mobile-app/.maestro/flows/02-login-validation.yaml
new file mode 100644
index 000000000..1dac9f7fe
--- /dev/null
+++ b/apps/mobile-app/.maestro/flows/02-login-validation.yaml
@@ -0,0 +1,51 @@
+# Test 02: Login Validation
+# Verifies login form validation and error handling
+#
+# Prerequisites: App is on login screen
+# Expected: Shows appropriate error messages for invalid input
+
+appId: net.aliasvault.app
+---
+# Launch the app fresh
+- launchApp:
+ clearState: true
+
+# Wait for login screen
+- extendedWaitUntil:
+ visible:
+ id: "login-screen"
+ timeout: 15000
+
+# Test 1: Empty form submission
+- tapOn:
+ id: "login-button"
+
+# Should show validation error
+- assertVisible:
+ text: "Username and password are required"
+ optional: true
+
+- takeScreenshot: "02-1-empty-form-validation"
+
+# Test 2: Invalid credentials
+- tapOn:
+ id: "username-input"
+- inputText: "[email protected]"
+
+- tapOn:
+ id: "password-input"
+- inputText: "wrongpassword"
+
+- hideKeyboard
+
+- tapOn:
+ id: "login-button"
+
+# Wait for error response (network request may take time)
+- extendedWaitUntil:
+ visible:
+ id: "error-message"
+ timeout: 15000
+ optional: true
+
+- takeScreenshot: "02-2-invalid-credentials"
diff --git a/apps/mobile-app/.maestro/flows/03-successful-login.yaml b/apps/mobile-app/.maestro/flows/03-successful-login.yaml
new file mode 100644
index 000000000..d4ffc8dc1
--- /dev/null
+++ b/apps/mobile-app/.maestro/flows/03-successful-login.yaml
@@ -0,0 +1,87 @@
+# Test 03: Successful Login
+# Verifies login flow with valid credentials against local API
+#
+# Prerequisites: Valid test user exists on local API server (http://localhost:5092)
+# Environment: TEST_USERNAME, TEST_PASSWORD must be set
+# Expected: User logs in and sees vault items screen
+
+appId: net.aliasvault.app
+---
+# Launch the app fresh
+- launchApp:
+ clearState: true
+
+# Wait for login screen
+- extendedWaitUntil:
+ visible:
+ id: "login-screen"
+ timeout: 15000
+
+# ===== Configure API URL to use local server =====
+
+# Tap on the server URL link to go to settings
+- tapOn:
+ id: "server-url-link"
+
+# Wait for settings screen to load
+- extendedWaitUntil:
+ visible: "Self-hosted"
+ timeout: 10000
+
+# Select "Self-hosted" option
+- tapOn:
+ text: "Self-hosted"
+
+# Wait for custom URL input to appear
+- extendedWaitUntil:
+ visible:
+ id: "custom-api-url-input"
+ timeout: 5000
+
+# Enter the local API URL
+- tapOn:
+ id: "custom-api-url-input"
+- inputText: "http://localhost:5092"
+
+- hideKeyboard
+
+# Go back to login screen (cross-platform)
+- runFlow: ../utils/go-back.yaml
+
+# Wait for login screen to be visible again
+- extendedWaitUntil:
+ visible:
+ id: "login-screen"
+ timeout: 10000
+
+# ===== Now perform login =====
+
+# Enter username
+- tapOn:
+ id: "username-input"
+- inputText: ${TEST_USERNAME}
+
+# Enter password
+- tapOn:
+ id: "password-input"
+- inputText: ${TEST_PASSWORD}
+
+- hideKeyboard
+
+- takeScreenshot: "03-1-credentials-entered"
+
+# Submit login
+- tapOn:
+ id: "login-button"
+
+# Wait for login to complete (may include vault sync)
+- extendedWaitUntil:
+ visible:
+ id: "items-screen"
+ timeout: 30000
+
+# Verify we're on the items/vault screen
+- assertVisible:
+ id: "items-list"
+
+- takeScreenshot: "03-2-login-successful"
diff --git a/apps/mobile-app/app/(tabs)/_layout.tsx b/apps/mobile-app/app/(tabs)/_layout.tsx
index 3384ba54c..52e3ce54f 100644
--- a/apps/mobile-app/app/(tabs)/_layout.tsx
+++ b/apps/mobile-app/app/(tabs)/_layout.tsx
@@ -104,6 +104,7 @@ export default function TabLayout() : React.ReactNode {
name="items"
options={{
title: t('navigation.vault'),
+ tabBarTestID: 'tab-items',
/**
* Icon for the vault tab.
*/
@@ -114,6 +115,7 @@ export default function TabLayout() : React.ReactNode {
name="emails"
options={{
title: t('navigation.emails'),
+ tabBarTestID: 'tab-emails',
/**
* Icon for the emails tab.
*/
@@ -124,6 +126,7 @@ export default function TabLayout() : React.ReactNode {
name="settings"
options={{
title: t('navigation.settings'),
+ tabBarTestID: 'tab-settings',
/**
* Icon for the settings tab.
*/
diff --git a/apps/mobile-app/app/(tabs)/emails/index.tsx b/apps/mobile-app/app/(tabs)/emails/index.tsx
index 90b9b8950..771c3c22e 100644
--- a/apps/mobile-app/app/(tabs)/emails/index.tsx
+++ b/apps/mobile-app/app/(tabs)/emails/index.tsx
@@ -221,7 +221,7 @@ export default function EmailsScreen() : React.ReactNode {
};
return (
- <ThemedContainer>
+ <ThemedContainer testID="emails-screen">
<CollapsibleHeader
title={t('emails.title')}
scrollY={scrollY}
diff --git a/apps/mobile-app/app/(tabs)/items/add-edit.tsx b/apps/mobile-app/app/(tabs)/items/add-edit.tsx
index fa5b4a3bc..f4f9b8f9a 100644
--- a/apps/mobile-app/app/(tabs)/items/add-edit.tsx
+++ b/apps/mobile-app/app/(tabs)/items/add-edit.tsx
@@ -1188,6 +1188,7 @@ export default function AddEditItemScreen(): React.ReactNode {
onPress={onSubmit}
style={[styles.headerRightButton, isSaveDisabled && styles.headerRightButtonDisabled]}
disabled={isSaveDisabled}
+ testID="save-button"
>
<MaterialIcons
name="save"
@@ -1215,7 +1216,7 @@ export default function AddEditItemScreen(): React.ReactNode {
<LoadingOverlay status={saveStatus} />
)}
- <ThemedContainer style={styles.container}>
+ <ThemedContainer style={styles.container} testID="add-edit-screen">
<KeyboardAvoidingView
style={{ flex: 1 }}
behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
@@ -1499,6 +1500,7 @@ export default function AddEditItemScreen(): React.ReactNode {
<RobustPressable
style={styles.deleteButton}
onPress={handleDelete}
+ testID="delete-item-button"
>
<ThemedText style={styles.deleteButtonText}>{t('items.deleteItem')}</ThemedText>
</RobustPressable>
diff --git a/apps/mobile-app/app/(tabs)/items/index.tsx b/apps/mobile-app/app/(tabs)/items/index.tsx
index ff4e459f8..1ed4cc24a 100644
--- a/apps/mobile-app/app/(tabs)/items/index.tsx
+++ b/apps/mobile-app/app/(tabs)/items/index.tsx
@@ -808,11 +808,13 @@ export default function ItemsScreen(): React.ReactNode {
numberOfLines={1}
onChangeText={setSearchQuery}
clearButtonMode={Platform.OS === 'ios' ? 'while-editing' : 'never'}
+ testID="search-input"
/>
{Platform.OS === 'android' && searchQuery.length > 0 && (
<TouchableOpacity
style={styles.clearButton}
onPress={() => setSearchQuery('')}
+ testID="clear-search-button"
>
<ThemedText style={styles.clearButtonText}>×</ThemedText>
</TouchableOpacity>
@@ -849,7 +851,7 @@ export default function ItemsScreen(): React.ReactNode {
};
return (
- <ThemedContainer style={styles.container}>
+ <ThemedContainer style={styles.container} testID="items-screen">
<CollapsibleHeader
title={t('items.title')}
scrollY={scrollY}
@@ -858,13 +860,14 @@ export default function ItemsScreen(): React.ReactNode {
/>
<ThemedView style={styles.stepContainer}>
{/* FAB */}
- <RobustPressable style={styles.fab} onPress={handleAddItem}>
+ <RobustPressable style={styles.fab} onPress={handleAddItem} testID="add-item-button">
<MaterialIcons name="add" style={styles.fabIcon} />
</RobustPressable>
{/* Item list */}
<Animated.FlatList
ref={flatListRef}
+ testID="items-list"
data={isLoadingItems ? Array(4).fill(null) : filteredItems}
keyExtractor={(itm, index) => itm?.Id ?? `skeleton-${index}`}
keyboardShouldPersistTaps='handled'
diff --git a/apps/mobile-app/app/(tabs)/settings/index.tsx b/apps/mobile-app/app/(tabs)/settings/index.tsx
index 662bf4bc9..ffe591b22 100644
--- a/apps/mobile-app/app/(tabs)/settings/index.tsx
+++ b/apps/mobile-app/app/(tabs)/settings/index.tsx
@@ -325,7 +325,7 @@ export default function SettingsScreen() : React.ReactNode {
});
return (
- <ThemedContainer>
+ <ThemedContainer testID="settings-screen">
<CollapsibleHeader
title={t('settings.title')}
scrollY={scrollY}
diff --git a/apps/mobile-app/app/login-settings.tsx b/apps/mobile-app/app/login-settings.tsx
index b30ea57f6..71c7e87f0 100644
--- a/apps/mobile-app/app/login-settings.tsx
+++ b/apps/mobile-app/app/login-settings.tsx
@@ -205,6 +205,7 @@ export default function SettingsScreen() : React.ReactNode {
autoCorrect={false}
multiline={false}
numberOfLines={1}
+ testID="custom-api-url-input"
/>
</View>
)}
diff --git a/apps/mobile-app/app/login.tsx b/apps/mobile-app/app/login.tsx
index 3e6efecab..ee8a85ed6 100644
--- a/apps/mobile-app/app/login.tsx
+++ b/apps/mobile-app/app/login.tsx
@@ -446,6 +446,10 @@ export default function LoginScreen() : React.ReactNode {
color: colors.textMuted,
fontSize: 14,
},
+ headerSubtitleContainer: {
+ alignItems: 'center',
+ flexDirection: 'row',
+ },
headerTitle: {
color: colors.text,
fontSize: 24,
@@ -500,6 +504,7 @@ export default function LoginScreen() : React.ReactNode {
<KeyboardAvoidingView
behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
style={styles.container}
+ testID="login-screen"
>
<ScrollView
style={styles.container}
@@ -525,19 +530,23 @@ export default function LoginScreen() : React.ReactNode {
<>
<View style={styles.headerContainer}>
<Text style={styles.headerTitle}>{t('auth.login')}</Text>
- <Text style={styles.headerSubtitle}>
- {t('auth.connectingTo')} {' '}
- <Text
- style={styles.clickableLink}
+ <View style={styles.headerSubtitleContainer}>
+ <Text style={styles.headerSubtitle}>
+ {t('auth.connectingTo')}{' '}
+ </Text>
+ <RobustPressable
onPress={() => router.push('/login-settings')}
+ testID="server-url-link"
>
- {getDisplayUrl()}
- </Text>
- </Text>
+ <Text style={styles.clickableLink}>
+ {getDisplayUrl()}
+ </Text>
+ </RobustPressable>
+ </View>
</View>
{error && (
- <View style={styles.errorContainer}>
+ <View style={styles.errorContainer} testID="error-message">
<Text style={styles.errorText}>{error}</Text>
</View>
)}
@@ -617,6 +626,7 @@ export default function LoginScreen() : React.ReactNode {
placeholderTextColor={colors.textMuted}
multiline={false}
numberOfLines={1}
+ testID="username-input"
/>
</View>
<Text style={styles.label}>{t('auth.password')}</Text>
@@ -638,6 +648,7 @@ export default function LoginScreen() : React.ReactNode {
autoCapitalize="none"
multiline={false}
numberOfLines={1}
+ testID="password-input"
/>
<RobustPressable
onPress={() => setShowPassword(!showPassword)}
@@ -654,6 +665,7 @@ export default function LoginScreen() : React.ReactNode {
style={[styles.button, styles.primaryButton]}
onPress={handleSubmit}
disabled={isLoading}
+ testID="login-button"
>
{isLoading ? (
<ActivityIndicator color={colors.text} />
diff --git a/apps/mobile-app/components/form/ItemNameField.tsx b/apps/mobile-app/components/form/ItemNameField.tsx
index a204fa36f..cde0031fe 100644
--- a/apps/mobile-app/components/form/ItemNameField.tsx
+++ b/apps/mobile-app/components/form/ItemNameField.tsx
@@ -177,6 +177,7 @@ export const ItemNameField = forwardRef<ItemNameFieldRef, IItemNameFieldProps>((
onChangeText={onChangeText}
placeholder={t('items.serviceName')}
placeholderTextColor={colors.textMuted}
+ testID="item-name-input"
/>
{hasFolders && (
<RobustPressable
diff --git a/apps/mobile-app/components/items/ItemCard.tsx b/apps/mobile-app/components/items/ItemCard.tsx
index 98720364a..27d4e4f4a 100644
--- a/apps/mobile-app/components/items/ItemCard.tsx
+++ b/apps/mobile-app/components/items/ItemCard.tsx
@@ -288,6 +288,7 @@ export function ItemCard({ item, onItemDelete }: ItemCardProps): React.ReactNode
// Ignore long press to prevent context menu long press from triggering the item card press.
}}
activeOpacity={0.7}
+ testID="item-card"
>
<View style={styles.itemContent}>
<ItemIcon item={item} style={styles.logo} />
diff --git a/apps/mobile-app/package.json b/apps/mobile-app/package.json
index dc9ee43ed..805495d26 100644
--- a/apps/mobile-app/package.json
+++ b/apps/mobile-app/package.json
@@ -9,6 +9,9 @@
"web": "expo start --web",
"test": "jest --passWithNoTests",
"test:watch": "jest --passWithNoTests --watchAll",
+ "test:e2e": "maestro test .maestro/flows/",
+ "test:e2e:android": "maestro test .maestro/flows/ --platform android",
+ "test:e2e:ios": "maestro test .maestro/flows/ --platform ios",
"lint": "eslint .",
"lint:fix": "eslint . --fix"
},
diff --git a/docs/misc/dev/mobile-apps/ios/e2e-testing.md b/docs/misc/dev/mobile-apps/ios/e2e-testing.md
new file mode 100644
index 000000000..7ca1a007b
--- /dev/null
+++ b/docs/misc/dev/mobile-apps/ios/e2e-testing.md
@@ -0,0 +1,135 @@
+# iOS E2E Testing with Maestro
+
+This guide explains how to set up and run end-to-end tests for the AliasVault iOS mobile app using [Maestro](https://maestro.mobile.dev/).
+
+## Prerequisites
+
+- macOS (required for iOS simulator)
+- Xcode installed with iOS Simulator
+- Node.js 20+
+- The AliasVault mobile app built and ready to run
+
+## Installing Maestro
+
+Install Maestro CLI:
+
+```bash
+curl -Ls "https://get.maestro.mobile.dev" | bash
+```
+
+After installation, restart your terminal or run:
+
+```bash
+export PATH="$PATH":"$HOME/.maestro/bin"
+```
+
+Verify the installation:
+
+```bash
+maestro --version
+```
+
+## Building the App for Testing
+
+Before running E2E tests, you need to build the app:
+
+```bash
+cd apps/mobile-app
+
+# Install dependencies
+npm install
+
+# Build and run on iOS simulator
+npm run ios
+```
+
+Wait for the app to fully launch in the simulator before running tests.
+
+## Running E2E Tests
+
+### Run All Tests
+
+```bash
+cd apps/mobile-app
+
+# Run all E2E tests on iOS
+npm run test:e2e:ios
+```
+
+### Run a Specific Test
+
+```bash
+# Run a single test file
+$HOME/.maestro/bin/maestro test .maestro/flows/01-app-launch.yaml --platform ios
+```
+
+### Run Tests with Environment Variables
+
+Some tests require credentials to log in:
+
+```bash
+TEST_USERNAME="your-test-user" TEST_PASSWORD="your-test-password" npm run test:e2e:ios
+```
+
+Or pass them directly to Maestro:
+
+```bash
+$HOME/.maestro/bin/maestro test .maestro/flows/03-successful-login.yaml \
+ --platform ios \
+ --env TEST_USERNAME="your-test-user" \
+ --env TEST_PASSWORD="your-test-password"
+```
+
+## Test Structure
+
+Tests are located in `apps/mobile-app/.maestro/`:
+
+```
+.maestro/
+├── config.yaml # Maestro configuration
+├── flows/ # Test flows (run in order)
+│ ├── 01-app-launch.yaml
+│ ├── 02-login-validation.yaml
+│ ├── 03-successful-login.yaml
+│ ├── 04-create-item.yaml
+│ └── ...
+└── utils/ # Reusable flows
+ └── go-back.yaml
+```
+
+## Debugging Failed Tests
+
+### View Screenshots
+
+Maestro saves screenshots and debug output to `~/.maestro/tests/`. After a test run, check this directory for:
+- Screenshots at failure points
+- JSON files with element hierarchy
+- HTML reports
+
+### Run in Debug Mode
+
+```bash
+maestro test .maestro/flows/01-app-launch.yaml --debug-output ./debug
+```
+
+### Interactive Studio
+
+Launch Maestro Studio to interactively build and debug tests:
+
+```bash
+maestro studio
+```
+
+This opens a web UI where you can:
+- See the current screen elements
+- Record actions
+- Test selectors
+
+## CI/CD Integration
+
+E2E tests are configured to run in GitHub Actions:
+
+- **Android tests**: Run on every PR (Linux runner)
+- **iOS tests**: Run on schedule/manual dispatch (macOS runner - higher cost)
+
+See `.github/workflows/mobile-e2e-tests.yml` for the CI configuration.