{post.title}
{post.author.name}
Posted {timeAgo}
{post.content}
{(await isMeticulousTest()) && (
/* Show test indicator in tests */
Running as test
)}
Posted {timeSincePost} ago
Posted {timeSincePost} ago
```
**Option 2: Configure in project settings**
Go to Project Settings → Screenshots & Flakes → Add CSS selectors to ignore:
```
.timestamp
.relative-time
[data-testid="posted-time"]
```
Learn more: [Fix False Positive Diffs](/docs/how-to/fix-false-positive-diffs)
---
## Complete Setup Example
### File Structure
```
your-app/
├── app/
│ ├── layout.tsx # Recorder installation
│ ├── page.tsx # Server Component
│ └── components/
│ └── client-component.tsx
├── instrumentation.ts # Math.random() seeding
├── lib/
│ └── date-utils.ts # getCurrentDate helper
├── .github/
│ └── workflows/
│ └── meticulous.yml # CI/CD
└── package.json
```
### Example: Server Component with Deterministic Rendering
**File**: `lib/date-utils.ts`
```typescript
import { headers } from 'next/headers'
export const getCurrentDate = async (): Promise...
}
```
### Pattern 2: Bypass Authentication in Tests
```typescript
import { headers } from 'next/headers'
import { redirect } from 'next/navigation'
export default async function ProtectedPage() {
const requestHeaders = await headers()
const isTest = requestHeaders.get('meticulous-is-test') === '1'
if (!isTest) {
const session = await getServerSession()
if (!session) {
redirect('/login')
}
}
// Render protected content
return Protected content
}
```
### Pattern 3: Use Mock Data for Tests
```typescript
import { headers } from 'next/headers'
async function getData() {
const requestHeaders = await headers()
const isTest = requestHeaders.get('meticulous-is-test') === '1'
if (isTest) {
// Return deterministic test data
return {
id: 'test-id-123',
name: 'Test User',
createdAt: new Date('2024-01-01T00:00:00Z')
}
}
// Fetch real data
const res = await fetch('https://api.example.com/data')
return res.json()
}
```
### Pattern 4: Handle Feature Flags
```typescript
import { headers } from 'next/headers'
async function getFeatureFlags() {
const requestHeaders = await headers()
const isTest = requestHeaders.get('meticulous-is-test') === '1'
if (isTest) {
// Use deterministic flags during tests
return {
newCheckout: true,
experimentalUI: false
}
}
// Fetch real flags from feature flag service
return await fetchFlags()
}
```
---
## CI/CD Configuration Details
> **info: The sections below apply to the cloud-compute (tunnel) path only**
> If you're using `upload-container` (the recommended approach), Meticulous serves your app from the uploaded image — there's no tunnel and no need for companion assets. The companion-assets, custom-tunnel-options, and similar sections below only apply if you're using `cloud-compute`.
### Why Companion Assets?
Next.js static assets (`/_next/static/`) are large and numerous. Serving them through the tunnel is slow.
**Without companion assets**:
```
Test Duration: ~5 minutes
Tunnel Traffic: ~50MB per test run
```
**With companion assets**:
```
Test Duration: ~2 minutes
Tunnel Traffic: ~5MB per test run
Performance: 60% faster
```
### Companion Assets Setup
**Step 1: Copy static files after build**
```yaml
- name: Build Next.js app
run: npm run build
- name: Prepare companion assets
run: |
mkdir -p companion-assets/_next
cp -r .next/static companion-assets/_next/
ls -la companion-assets # Verify files copied
```
**Step 2: Configure Meticulous action**
```yaml
- name: Run Meticulous tests
uses: alwaysmeticulous/report-diffs-action/cloud-compute@v1
with:
api-token: ${{ secrets.METICULOUS_API_TOKEN }}
app-url: "http://localhost:3000"
companion-assets-folder: "companion-assets"
companion-assets-regex: "^/_next/static/"
```
**How it works**:
1. Meticulous intercepts requests matching `^/_next/static/`
2. Files are served from `companion-assets/_next/static/`
3. Other requests go through tunnel to running app
---
### Environment Variables
**Build-time variables** (prefixed with `NEXT_PUBLIC_`):
```yaml
- name: Build Next.js app
run: npm run build
env:
NEXT_PUBLIC_API_URL: "http://localhost:3000/api"
NODE_ENV: production
```
**Runtime variables** (server-side only):
```yaml
- name: Start app
run: npm start &
env:
DATABASE_URL: "postgresql://..."
API_SECRET: ${{ secrets.API_SECRET }}
```
---
## Troubleshooting
### Issue: "Failed to fetch RSC payload"
**Symptom**: Console errors about RSC fetch failures
**Cause**: Network stubbing is blocking Server Component requests
**Fix**: Update project settings to allow Server Component requests (see step 4 in Quick Start)
---
### Issue: Timestamps Cause False Positives
**Symptom**: Diffs showing "Posted 5 min ago" vs "Posted 6 min ago"
**Causes**:
1. Not using a simulated date header for server-side rendering
2. Using `Date.now()` or `new Date()` in Server Components
**Fix**: Configure a simulated date header in Meticulous project settings using the Simulated Date template, then use the `getCurrentDate()` helper (see Handling Timestamps section)
---
### Issue: Math.random() Produces Different Results
**Symptom**: Random UUIDs, shuffled arrays, or randomized content causes diffs
**Fix**: Install seedrandom and setup instrumentation.ts (see Handling Math.random() section)
---
### Issue: Companion Assets Not Loading
**Symptom**: Console errors for `/_next/static/` files, or slow test runs
**Checks**:
1. Verify folder exists: `ls -la companion-assets/_next/static`
2. Check files were copied: Should see CSS/JS files
3. Verify regex pattern matches: `^/_next/static/` should match `/_next/static/chunks/123.js`
4. Check workflow syntax: Both `companion-assets-folder` and `companion-assets-regex` required
**Debug**:
```yaml
- name: Debug companion assets
run: |
echo "Checking companion assets..."
ls -la companion-assets/_next/static || echo "Directory not found"
find companion-assets -type f | head -10
```
---
### Issue: App Doesn't Start in CI
**Symptom**: "ECONNREFUSED" or "Failed to connect to http://localhost:3000"
**Common causes**:
1. Build failed silently
2. Port already in use
3. Missing environment variables
4. App requires database connection
**Debug steps**:
```yaml
- name: Start app with logging
run: |
npm start > app.log 2>&1 &
sleep 5
cat app.log # Check for startup errors
- name: Verify app is running
run: |
curl http://localhost:3000 || echo "App not responding"
npx wait-on http://localhost:3000 --timeout 60000
```
---
### Issue: Authentication Blocks Tests
**Symptom**: Tests fail because pages redirect to login
**Solutions**:
**Option 1: Bypass auth in tests** (recommended)
```typescript
import { headers } from 'next/headers'
const isMeticulousTest = async () => {
const requestHeaders = await headers()
return requestHeaders.get('meticulous-is-test') === '1'
}
export default async function ProtectedLayout({ children }) {
if (!(await isMeticulousTest())) {
const session = await getServerSession()
if (!session) redirect('/login')
}
return <>{children}
}
```
**Option 2: Mock authentication**
```typescript
if (isMeticulousTest()) {
// Return mock session for tests
return {
user: { id: 'test-user', name: 'Test User' }
}
}
```
See full guide: [Troubleshoot Authentication](/docs/how-to/troubleshoot-auth)
---
## Advanced Configuration
### Custom Tunnel Options
If you need to proxy multiple ports or use HTTPS:
```yaml
- name: Run Meticulous tests
uses: alwaysmeticulous/report-diffs-action/cloud-compute@v1
with:
api-token: ${{ secrets.METICULOUS_API_TOKEN }}
app-url: "http://localhost:3000"
proxy-all-urls: true # Proxy all domains, not just app-url
companion-assets-folder: "companion-assets"
companion-assets-regex: "^/_next/static/"
```
See: [Tunnel Advanced Options](/docs/how-to/tunnel-advanced-options)
---
### Monorepo Setup
If your Next.js app is in a subdirectory:
```yaml
- name: Install dependencies
working-directory: ./apps/frontend
run: npm ci
- name: Build app
working-directory: ./apps/frontend
run: npm run build
- name: Prepare companion assets
working-directory: ./apps/frontend
run: |
mkdir -p companion-assets/_next
cp -r .next/static companion-assets/_next/
- name: Start app
working-directory: ./apps/frontend
run: npm start &
- name: Run Meticulous tests
uses: alwaysmeticulous/report-diffs-action/cloud-compute@v1
with:
api-token: ${{ secrets.METICULOUS_API_TOKEN }}
app-url: "http://localhost:3000"
companion-assets-folder: "./apps/frontend/companion-assets"
companion-assets-regex: "^/_next/static/"
```
---
## Testing Best Practices
### 1. Record Real User Sessions
Record sessions in staging or production (with appropriate privacy controls):
```typescript
// Only load recorder in staging/production
const shouldLoadRecorder =
process.env.NEXT_PUBLIC_ENV === 'staging' ||
process.env.NEXT_PUBLIC_ENV === 'production'
export default function RootLayout({ children }) {
return (
{shouldLoadRecorder && (
)}
{children}
)
}
```
### 2. Curate Your Test Suite
Review recorded sessions in the dashboard and select high-value flows:
- Critical user journeys (signup, checkout, etc.)
- High-traffic pages
- Recently changed features
- Edge cases
### 3. Handle Dynamic Content
For content that changes frequently (ads, recommendations, live data):
```typescript
{/* Content that changes frequently */}
```
### 4. Test Locally Before CI
Run tests locally to catch issues faster:
```bash
# Start your app
npm run dev
# In another terminal, run Meticulous CLI
npx @alwaysmeticulous/cli simulate \
--sessionId="YOUR_SESSION_ID" \
--appUrl="http://localhost:3000"
```
---
## Migration from Pages Router
If you're migrating from Pages Router to App Router:
1. **Keep recorder in head**: Move from `_document.tsx` to `app/layout.tsx`
2. **Update network stubbing**: Enable Server Component request passthrough
3. **Update Math.random() calls**: Use `createDeterministicRandom()` helper in Server Components
4. **Update date handling**: Use `getCurrentDate()` helper in Server Components
5. **Test thoroughly**: Server Components behave differently than client components
---
## Example Repository
The configuration above is a complete App Router setup.
---
## See Also
- [Onboarding Guide](/docs/onboarding-guide) - General Meticulous setup
- [Network Stubbing Explanation](/docs/concepts/network-recording-and-patching) - How API mocking works
- [Fix False Positives](/docs/how-to/fix-false-positive-diffs) - Handle non-deterministic content
- [Troubleshoot Authentication](/docs/how-to/troubleshoot-auth) - Auth patterns and solutions
- [Companion Assets Guide](/docs/how-to/companion-assets-advanced) - Deep dive into static asset optimization