End-to-End (E2E) Testing

js-validation uses Playwright for browser-level end-to-end tests. These tests verify validation behaviour in a real browser environment against static HTML fixture pages served by Vite.

Stack

Browsers tested: Chromium, Firefox, WebKit (Safari engine).

Configuration

Playwright (playwright.config.js)

export default defineConfig({
  fullyParallel: true,
  testDir: './test/e2e',
  use: {
    baseURL: 'http://localhost:5174',
    headless: true,
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
  webServer: {
    command: 'npx vite --port 5174 --config vite.config.e2e.js',
    port: 5174,
    reuseExistingServer: !process.env.CI,
  },
});

Vite E2E Server (vite.config.e2e.js)

export default defineConfig({
  root: resolve(__dirname, 'test/e2e'),
  server: { port: 5174 },
  resolve: {
    alias: { '/src': resolve(__dirname, 'src') },
  },
});

The server root is test/e2e/, so a test calling page.goto('/fixture.html') loads test/e2e/fixture.html, and page.goto('/alpha/fixture.html') loads test/e2e/alpha/fixture.html.

Running Tests

# Run all E2E tests (all 3 browsers)
npm run test:e2e

# Run unit tests (Vitest)
npm test

On CI Playwright always starts a fresh server. Locally it reuses an existing server on port 5174 if one is already running.

Directory Structure

test/e2e/
├── fixture.html          ← Shared base fixture (multi-rule form)
├── validation.spec.js    ← Tests for the shared fixture
├── alpha/
│   ├── fixture.html      ← Fixture for the alpha rule
│   └── alpha.spec.js     ← Tests for the alpha rule
├── email/
│   ├── fixture.html
│   └── email.spec.js
├── locales/
│   ├── fixture.html      ← Fixture for localization tests
│   └── locales.spec.js   ← Tests for locale switching
├── minlength/
├── maxlength/
├── required/
└── … (one sub-directory per rule)

Fixture Page Pattern

A fixture page is a minimal HTML file that:

1. Renders a <form novalidate> with the relevant input(s)
2. Imports js-validation from /src/index.js
3. Initialises the validator with rules and an optional submit handler
4. Exposes a #status element that shows 'Form submitted successfully!' on success

Shared fixture (test/e2e/fixture.html)

<form id="test-form" novalidate>
  <div><input name="username" id="username" type="text" /></div>
  <div><input name="email"    id="email"    type="text" /></div>
  <div><input name="password" id="password" type="password" /></div>
  <div><input name="confirmPassword" id="confirmPassword" type="password" /></div>
  <button type="submit" id="submit-btn">Submit</button>
</form>
<p id="status"></p>

<script type="module">
  import jsValidation from '/src/index.js';

  jsValidation('#test-form', {
    rules: {
      username:        { required: true, minlength: 3 },
      email:           { required: true, email: true },
      password:        { required: true, minlength: 6 },
      confirmPassword: { required: true, equalTo: '#password' }
    },
    messages: {
      confirmPassword: { equalTo: 'Passwords must match.' }
    }
  }).submit(() => {
    document.getElementById('status').textContent = 'Form submitted successfully!';
  });
</script>

Rule-specific fixture (test/e2e/alpha/fixture.html)

<form id="test-form" novalidate>
  <div><input name="field" id="field" type="text" /></div>
  <button type="submit" id="submit-btn">Submit</button>
</form>
<p id="status"></p>

<script type="module">
  import jsValidation from '/src/index.js';

  jsValidation('#test-form', {
    rules: { field: { required: true, alpha: true } },
    messages: { field: { alpha: 'Please enter only alphabetic letters.' } }
  }).submit(() => {
    document.getElementById('status').textContent = 'Form submitted successfully!';
  });
</script>

Writing Specs

Place specs inside test/e2e/<rule-name>/<rule-name>.spec.js for rule-specific tests, or in test/e2e/validation.spec.js for cross-cutting concerns.

Anatomy of a spec file

import { test, expect } from '@playwright/test';

test.describe('E2E: <rule> rule', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/<rule>/fixture.html');
  });

  test('fails for invalid value', async ({ page }) => {
    await page.fill('#field', 'bad-value');
    await page.click('#submit-btn');
    await expect(page.locator('#field')).toHaveClass(/is-invalid/);
  });

  test('passes for valid value', async ({ page }) => {
    await page.fill('#field', 'good-value');
    await page.click('#submit-btn');
    await expect(page.locator('#status')).toHaveText('Form submitted successfully!');
  });
});

Key DOM contracts

Test Coverage — Shared Fixture

Test Coverage — Locales

Adding E2E Tests for a New Rule

1. Create a fixture at test/e2e/<rule>/fixture.html (copy an existing one and adapt the rules).
2. Create a spec at test/e2e/<rule>/<rule>.spec.js.
3. Run npm run test:e2e to verify.

Checklist for a complete spec

• Fails for each documented invalid input variant
• Passes for each valid input variant
• Verifies is-invalid class added/removed correctly
• Verifies data-jsv-message attribute on failure
• Verifies inline error element ([data-jsv-error-for]) visibility
• Verifies successful form submission path

Debugging Tips