rtl-rendering-tester
Build-an-X workflow for verifying RTL (right-to-left) layouts - runs the test suite under Arabic / Hebrew / Persian / Urdu locales, asserts the `dir="rtl"` attribute is set, verifies layout mirrors correctly (text alignment, icon positions, scrollbar location), uses logical CSS properties (`start`/`end` over `left`/`right`) per W3C guidance, captures per-locale screenshots for visual review. Use when the app supports RTL languages.
rtl-rendering-tester
Overview
Per w3-rtl:
"If the overall document direction is right-to-left, add
dir='rtl'to thehtmltag."
The dir attribute is the standard way to signal direction. Per w3-rtl, it affects:
Common RTL languages: Arabic, Hebrew, Persian, Urdu.
This skill verifies the app handles RTL correctly.
When to use
Step 1 - Verify dir attribute presence
import { test, expect } from '@playwright/test';
test.use({ extraHTTPHeaders: { 'Accept-Language': 'ar' } });
test('Arabic locale sets dir=rtl on <html>', async ({ page }) => {
await page.goto('/');
const dir = await page.locator('html').getAttribute('dir');
expect(dir).toBe('rtl');
});
test('Hebrew locale sets dir=rtl on <html>', async ({ page }) => {
await page.goto('/?lng=he');
await expect(page.locator('html')).toHaveAttribute('dir', 'rtl');
});Per w3-rtl: the html-level dir is the canonical signal; CSS-only direction setting is incorrect:
"Do not use CSS to apply base direction in HTML pages. Direction is semantic content and should reside in markup, not styling."
Step 2 - Verify text alignment
test('text aligns right in RTL', async ({ page }) => {
await page.goto('/?lng=ar');
const heading = page.locator('h1').first();
const align = await heading.evaluate(el => getComputedStyle(el).textAlign);
expect(['right', 'start']).toContain(align); // 'start' resolves to right in RTL
});Per w3-rtl: prefer logical properties (start, end) over directional (left, right) so the layout flips automatically.
Step 3 - Verify icon positions
Common RTL gotchas:
test('back arrow mirrors in RTL', async ({ page }) => {
await page.goto('/cart?lng=ar');
const backArrow = page.getByRole('link', { name: /back/i });
const transform = await backArrow.evaluate(el => getComputedStyle(el).transform);
// RTL should apply scaleX(-1) (or use a different mirrored asset)
expect(transform).toContain('-1');
});Step 4 - Bidi text in mixed contexts
Mixed LTR + RTL content is a common bidi issue:
"My order #ORD-12345 has shipped."In Arabic locale, the order number "ORD-12345" must remain LTR inside the RTL paragraph. Without proper bidi markers, the ordering can flip.
test('order number preserves LTR direction inside RTL paragraph', async ({ page }) => {
await page.goto('/orders/ORD-12345?lng=ar');
const paragraph = page.locator('p').filter({ hasText: 'ORD-12345' });
const orderNumber = paragraph.locator('bdi, [dir="ltr"]');
await expect(orderNumber).toBeVisible();
await expect(orderNumber).toHaveText('ORD-12345');
});The <bdi> element or dir="ltr" on a span isolates LTR text within an RTL block - without it, browser bidi heuristics may flip.
Step 5 - Form input behavior
Per w3-rtl: in RTL, "Form inputs start at the right by default."
test('form inputs start at right in RTL', async ({ page }) => {
await page.goto('/checkout?lng=he');
const emailField = page.getByLabel(/email/i);
await emailField.click();
// Cursor / placeholder text should be at the right edge
// (assert via screenshot or computed-style direction)
await expect(emailField).toHaveCSS('text-align', /(right|start)/);
});Step 6 - Per-locale visual regression
test('home page Arabic snapshot', async ({ page }) => {
await page.goto('/?lng=ar');
await expect(page).toHaveScreenshot('home-ar.png');
});
test('home page Hebrew snapshot', async ({ page }) => {
await page.goto('/?lng=he');
await expect(page).toHaveScreenshot('home-he.png');
});RTL screenshots catch regressions like:
Step 7 - CI integration
- name: RTL rendering tests
run: npx playwright test e2e/rtl/ --project=mobile-iphone-15 --project=desktop-chromium
- uses: actions/upload-artifact@v4
if: failure()
with:
name: rtl-screenshots
path: test-results/Run on both desktop and mobile profiles - RTL handling can differ per breakpoint.
Step 8 - dirname for form submission
Per w3-rtl: "Use dir='auto' to automatically detect text direction from the first strongly-typed character. Pair with the dirname attribute to send information about direction to the server in addition to the usual form data."
Verify forms submitted from RTL contexts include the direction information when needed:
test('comment form sends direction with submission', async ({ page }) => {
await page.goto('/post/123?lng=ar');
await page.getByLabel(/comment/i).fill('مرحبا — hello');
// Listen for the form submission
const responsePromise = page.waitForResponse('/api/comments');
await page.getByRole('button', { name: /submit/i }).click();
const response = await responsePromise;
// The form's `dirname` attribute should send a separate field with the direction
expect(response.request().postData()).toContain('comment.dir=rtl');
});Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| CSS-only direction | Per w3-rtl: "Do not use CSS to apply base direction." | dir="rtl" on the html tag (Step 1). |
Hardcoded left / right in CSS | Doesn't mirror in RTL. | Logical properties (start / end) per w3-rtl. |
| Mirroring brand logos / icons with embedded text | Brand recognition + readability suffer. | Per-asset decision; not all icons mirror. |
Order numbers / IDs without <bdi> / dir="ltr" isolation | Bidi heuristics may flip; "ORD-12345" becomes "12345-ORD". | Wrap in <bdi> (Step 4). |
| Skipping per-locale visual regression | Regressions visible only when RTL activated. | Per-locale screenshots (Step 6). |