Preview & Test

Testing your documentation locally ensures everything works correctly before deploying to production. Mordoc provides development and preview modes for testing.

Development Server

Start the development server for live editing:

npm run dev

Development Server Features

• Hot Reload: Automatically refreshes when files change
• Live Preview: See edits in real-time
• Fast Compilation: Quick rebuilds for iteration
• Error Reporting: Console errors for issues
• Port Configuration: Customizable port

Server Output

$ npm run dev

> mordoc dev

  Mordoc Dev Server

  ➜  Local:   http://localhost:3000/
  ➜  Network: http://192.168.1.100:3000/

  Ready in 847ms

Access Your Site

Open your browser to:

• Local: http://localhost:3000
• Network: Access from other devices on your network

Custom Port

Change the default port (3000):

npm run dev -- --port 8080

Or configure in package.json:

{
  "scripts": {
    "dev": "mordoc dev --port 8080"
  }
}

Preview Production Build

Preview the built site locally before deployment:

npm run build
npm run preview

Preview vs Development

When to Use Preview

Use npm run preview to:

• Test the production build locally
• Verify search functionality
• Check optimization results
• Test before deploying
• Debug production-only issues

Testing Checklist

Content Testing

• [ ] All pages load correctly
• [ ] Links work (internal and external)
• [ ] Images display properly
• [ ] Code blocks render with syntax highlighting
• [ ] Tables format correctly
• [ ] Lists display properly
• [ ] Callouts show with correct styles

Navigation Testing

• [ ] Side navigation displays all pages
• [ ] Navigation hierarchy is correct
• [ ] Active page is highlighted
• [ ] Nested pages expand/collapse
• [ ] Mobile navigation works
• [ ] Breadcrumbs are accurate

Functional Testing

• [ ] Search finds relevant content
• [ ] Table of contents shows page sections
• [ ] TOC highlights current section on scroll
• [ ] Dark/light mode toggle works
• [ ] Copy code button functions
• [ ] All interactive elements work

Visual Testing

• [ ] Logo displays correctly
• [ ] Colors match brand guidelines
• [ ] Typography is consistent
• [ ] Spacing and layout are correct
• [ ] Cards and grids align properly
• [ ] Mobile layout is responsive

Performance Testing

• [ ] Pages load quickly
• [ ] Images are optimized
• [ ] No console errors
• [ ] Smooth scrolling
• [ ] Fast search results

Browser Testing

Test in multiple browsers:

Browser DevTools

Use browser developer tools:

Chrome DevTools:

• Press F12 or Ctrl+Shift+I
• Check Console for errors
• Use Network tab for performance
• Test responsive layouts

Firefox DevTools:

• Press F12 or Ctrl+Shift+I
• Similar features to Chrome
• Good for CSS debugging

Responsive Testing

Test different screen sizes:

Device Breakpoints

Testing Methods

Browser DevTools:

1. Open DevTools (F12)
2. Click device toolbar icon
3. Select device or custom size
4. Test navigation and layout

Physical Devices:

• Test on actual phones/tablets
• Check touch interactions
• Verify mobile navigation
• Test performance

Network Testing

Test with different network conditions:

Slow Connection Testing

Chrome DevTools:

1. Open DevTools
2. Network tab
3. Throttle to "Slow 3G"
4. Reload page

Check:

• Page load time
• Image loading
• Search index download
• User experience on slow connections

Accessibility Testing

Keyboard Navigation

Test without a mouse:

• [ ] Tab navigates through links
• [ ] Enter activates links/buttons
• [ ] Esc closes modals/menus
• [ ] / or Ctrl+K opens search
• [ ] Arrow keys navigate search results

Screen Reader Testing

Tools:

• Windows: NVDA (free)
• macOS: VoiceOver (built-in)
• Linux: Orca

Test:

• Page structure makes sense
• Headings are announced correctly
• Links are descriptive
• Images have alt text
• Forms are labeled

Color Contrast

Use tools to check contrast:

• WebAIM Contrast Checker
• Chrome DevTools Lighthouse
• WAVE Browser Extension

Requirements:

• Normal text: 4.5:1 minimum
• Large text: 3:1 minimum
• UI components: 3:1 minimum

SEO Testing

Meta Tags

Verify each page has:

• <title> tag (unique per page)
• Meta description
• Open Graph tags
• Canonical URL

Check in browser:

View → Developer → View Source

Sitemap

Verify sitemap generated:

http://localhost:3000/sitemap.xml

Should list all pages with:

• Full URLs
• Last modified dates
• Priority (optional)

Robots.txt

Check robots.txt exists:

http://localhost:3000/robots.txt

Performance Testing

Lighthouse Audit

Run Lighthouse in Chrome:

1. Open DevTools (F12)
2. Click "Lighthouse" tab
3. Select categories
4. Click "Generate report"

Target scores:

• Performance: 90+
• Accessibility: 95+
• Best Practices: 95+
• SEO: 95+

Page Speed

Check load times:

Chrome DevTools:

1. Network tab
2. Reload page (Ctrl+Shift+R)
3. Check load time at bottom

Target:

• Initial load: < 3 seconds
• Subsequent pages: < 1 second

Bundle Size

Check build output:

npm run build -- --analyze

Optimize if needed:

• Compress images
• Minify assets
• Enable lazy loading
• Code splitting

Link Checking

Manual Link Testing

Click through all links to verify:

• Internal links go to correct pages
• External links open in new tabs
• Anchor links scroll to sections
• No 404 errors

Automated Link Checking

Use link checker tools:

broken-link-checker:

npx broken-link-checker http://localhost:3000 --recursive

linkinator:

npx linkinator http://localhost:3000 --recurse

Content Validation

Markdown Linting

Lint markdown files:

npx markdownlint content/**/*.md

HTML Validation

Validate generated HTML:

npm run build
npx html-validator dist/index.html

Or use W3C Validator

Spell Checking

Check spelling:

npx cspell "content/**/*.md"

Local HTTPS Testing

For testing HTTPS features locally:

Using mkcert

# Install mkcert
npm install -g mkcert

# Create certificate
mkcert create-ca
mkcert create-cert

# Run with HTTPS
npm run dev -- --https

Common Testing Issues

Hot Reload Not Working

• Save files properly
• Check file watcher limits (Linux)
• Restart development server
• Check console for errors

Search Not Working in Dev

Search may be limited in development mode. Test with:

npm run build
npm run preview

Styles Not Updating

• Clear browser cache (Ctrl+Shift+R)
• Check CSS file is saved
• Restart dev server
• Verify file paths are correct

Images Not Loading

• Check file exists in public/
• Verify path starts with /
• Check file name case (case-sensitive)
• Rebuild: npm run build

Testing Workflow

Daily Development

# Start dev server
npm run dev

# Edit content
# Save files
# Check browser automatically reloads
# Iterate

Pre-Deployment

# 1. Build for production
npm run build

# 2. Preview locally
npm run preview

# 3. Run tests
npm test

# 4. Check links
npx linkinator http://localhost:3000 --recurse

# 5. Run Lighthouse audit

# 6. If all passes, deploy

Automated Testing

Jest Tests

Add tests in tests/ directory:

// tests/navigation.test.js
describe('Navigation', () => {
  test('all nav items have valid paths', () => {
    const sidenav = require('../config/sidenav.yaml');
    // Test navigation structure
  });
});

Run tests:

npm test

CI/CD Testing

GitHub Actions:

name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run build
      - run: npm test
      - run: npx linkinator http://localhost:3000

Best Practices

Regular Testing

• Test during development, not just before deployment
• Check changes in multiple browsers
• Test on actual mobile devices
• Run accessibility audits regularly

Documentation Testing

• Read through content as a user would
• Verify instructions are clear
• Test all code examples
• Check cross-references

Performance Monitoring

• Keep build sizes reasonable
• Optimize images before adding
• Monitor page load times
• Check bundle size regularly

Next Steps

After thorough testing:

1. Version Control - Commit your changes
2. Launch - Deploy to production
3. Continue testing in production environment