✅(export) add PDF regression tests

To avoid regression issues in PDF export
functionality, this commit introduces end-to-end
tests that compare exported PDFs against
known good reference files.
We compare the PDF on most of the blocks
that the editor supports.
If during a Blocknote release or pull request
there are intentional changes, the reference
files would need to be updated accordingly.
It can be done by uncommenting the line
in the test that saves the newly generated
PDF to the assets folder.

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to
 ### Added
 
 - ✨(backend) add documents/all endpoint with descendants #1553
+- ✅(export) add PDF regression tests #1762
 
 ## [4.3.0] - 2026-01-05
 

src/frontend/apps/e2e/__tests__/app-impress/doc-editor.spec.ts

@@ -604,7 +604,7 @@ test.describe('Doc Editor', () => {
 
     await verifyDocName(page, randomDoc);
 
-    const editor = await openSuggestionMenu({ page });
+    const { editor } = await openSuggestionMenu({ page });
     await page.getByText('Embedded file').click();
     await page.getByText('Upload file').click();
 

src/frontend/apps/e2e/__tests__/app-impress/doc-export.spec.ts

@@ -1,6 +1,7 @@
+import fs from 'fs';
 import path from 'path';
 
-import { expect, test } from '@playwright/test';
+import { Download, expect, test } from '@playwright/test';
 import cs from 'convert-stream';
 import JSZip from 'jszip';
 import { PDFParse } from 'pdf-parse';
@@ -633,4 +634,151 @@ test.describe('Doc Export', () => {
     const download = await downloadPromise;
     expect(download.suggestedFilename()).toBe(`${docChild}.odt`);
   });
+
+  test('it exports the doc to PDF and checks regressions', async ({
+    page,
+    browserName,
+  }) => {
+    // Override content prop with assets/base-content-test-pdf.txt
+    await page.route(/\**\/documents\/\**/, async (route) => {
+      const request = route.request();
+      if (
+        request.method().includes('GET') &&
+        !request.url().includes('page=') &&
+        !request.url().includes('versions') &&
+        !request.url().includes('accesses') &&
+        !request.url().includes('invitations')
+      ) {
+        const response = await route.fetch();
+        const json = await response.json();
+        json.content = fs.readFileSync(
+          path.join(__dirname, 'assets/base-content-test-pdf.txt'),
+          'utf-8',
+        );
+        void route.fulfill({
+          response,
+          body: JSON.stringify(json),
+        });
+      } else {
+        await route.continue();
+      }
+    });
+
+    const [randomDoc] = await createDoc(
+      page,
+      'doc-export-regressions',
+      browserName,
+      1,
+    );
+
+    await verifyDocName(page, randomDoc);
+
+    // Add Image SVG
+    await page.keyboard.press('Enter');
+    const { suggestionMenu } = await openSuggestionMenu({ page });
+    await suggestionMenu.getByText('Resizable image with caption').click();
+    const fileChooserPromise = page.waitForEvent('filechooser');
+    await page.getByText('Upload image').click();
+    const fileChooser = await fileChooserPromise;
+    await fileChooser.setFiles(path.join(__dirname, 'assets/test.svg'));
+    const image = page
+      .locator('.--docs--editor-container img.bn-visual-media[src$=".svg"]')
+      .first();
+    await expect(image).toBeVisible();
+    await page.keyboard.press('Enter');
+
+    // Add Image PNG
+    await openSuggestionMenu({ page });
+    await suggestionMenu.getByText('Resizable image with caption').click();
+    const fileChooserPNGPromise = page.waitForEvent('filechooser');
+    await page.getByText('Upload image').click();
+    const fileChooserPNG = await fileChooserPNGPromise;
+    await fileChooserPNG.setFiles(
+      path.join(__dirname, 'assets/logo-suite-numerique.png'),
+    );
+    const imagePng = page
+      .locator('.--docs--editor-container img.bn-visual-media[src$=".png"]')
+      .first();
+    await expect(imagePng).toBeVisible();
+
+    await page
+      .getByRole('button', {
+        name: 'Export the document',
+      })
+      .click();
+
+    await expect(
+      page.getByTestId('doc-open-modal-download-button'),
+    ).toBeVisible();
+
+    const downloadPromise = page.waitForEvent('download', (download) => {
+      return download.suggestedFilename().includes(`${randomDoc}.pdf`);
+    });
+
+    await page.getByTestId('doc-export-download-button').click();
+
+    const download = await downloadPromise;
+    expect(download.suggestedFilename()).toBe(`${randomDoc}.pdf`);
+
+    // If we need to update the PDF regression fixture, uncomment the line below
+    //await savePDFToAssetFolder(download);
+
+    // Assert the generated PDF matches "assets/doc-export-regressions.pdf"
+    await comparePDFWithAssetFolder(download);
+  });
 });
+
+export const savePDFToAssetFolder = async (download: Download) => {
+  const pdfBuffer = await cs.toBuffer(await download.createReadStream());
+  const pdfPath = path.join(__dirname, 'assets', `doc-export-regressions.pdf`);
+  fs.writeFileSync(pdfPath, pdfBuffer);
+};
+
+export const comparePDFWithAssetFolder = async (download: Download) => {
+  const pdfBuffer = await cs.toBuffer(await download.createReadStream());
+
+  // Load reference PDF for comparison
+  const referencePdfPath = path.join(
+    __dirname,
+    'assets',
+    'doc-export-regressions.pdf',
+  );
+
+  const referencePdfBuffer = fs.readFileSync(referencePdfPath);
+
+  // Parse both PDFs
+  const generatedPdf = new PDFParse({ data: pdfBuffer });
+  const referencePdf = new PDFParse({ data: referencePdfBuffer });
+
+  const [generatedInfo, referenceInfo] = await Promise.all([
+    generatedPdf.getInfo(),
+    referencePdf.getInfo(),
+  ]);
+
+  const [generatedScreenshot, referenceScreenshot] = await Promise.all([
+    generatedPdf.getScreenshot(),
+    referencePdf.getScreenshot(),
+  ]);
+  generatedScreenshot.pages[0].data;
+
+  const [generatedText, referenceText] = await Promise.all([
+    generatedPdf.getText(),
+    referencePdf.getText(),
+  ]);
+
+  // Compare page count
+  expect(generatedInfo.total).toBe(referenceInfo.total);
+
+  // Compare text content
+  expect(generatedText.text).toBe(referenceText.text);
+
+  // Compare screenshots page by page
+  for (let i = 0; i < generatedScreenshot.pages.length; i++) {
+    const genPage = generatedScreenshot.pages[i];
+    const refPage = referenceScreenshot.pages[i];
+
+    expect(genPage.width).toBe(refPage.width);
+    expect(genPage.height).toBe(refPage.height);
+    expect(genPage.data).toStrictEqual(refPage.data);
+  }
+};

src/frontend/apps/e2e/__tests__/app-impress/doc-version.spec.ts

@@ -42,8 +42,8 @@ test.describe('Doc Version', () => {
     // Write more
     await writeInEditor({ page, text: 'It will create a version' });
 
-    await openSuggestionMenu({ page });
-    await page.getByText('Add a callout block').click();
+    const { suggestionMenu } = await openSuggestionMenu({ page });
+    await suggestionMenu.getByText('Add a callout block').click();
 
     const calloutBlock = page
       .locator('div[data-content-type="callout"]')

src/frontend/apps/e2e/__tests__/app-impress/language.spec.ts

@@ -109,8 +109,10 @@ test.describe('Language', () => {
   }) => {
     await createDoc(page, 'doc-toolbar', browserName, 1);
 
-    const editor = await openSuggestionMenu({ page });
-    await expect(page.getByText('Headings', { exact: true })).toBeVisible();
+    const { editor, suggestionMenu } = await openSuggestionMenu({ page });
+    await expect(
+      suggestionMenu.getByText('Headings', { exact: true }),
+    ).toBeVisible();
 
     await editor.click(); // close the menu
 
@@ -121,6 +123,8 @@ test.describe('Language', () => {
 
     // Trigger slash menu to show french menu
     await openSuggestionMenu({ page });
-    await expect(page.getByText('Titres', { exact: true })).toBeVisible();
+    await expect(
+      suggestionMenu.getByText('Titres', { exact: true }),
+    ).toBeVisible();
   });
 });

src/frontend/apps/e2e/__tests__/app-impress/utils-editor.ts

@@ -11,7 +11,9 @@ export const openSuggestionMenu = async ({ page }: { page: Page }) => {
   await editor.click();
   await writeInEditor({ page, text: '/' });
 
-  return editor;
+  const suggestionMenu = page.locator('.bn-suggestion-menu');
+
+  return { editor, suggestionMenu };
 };
 
 export const writeInEditor = async ({