docs(api): add refresh button to examples (#3301)

* docs(api): add refresh button to examples

* chore: improve button behavior slightly

* chore: improve output format

* chore: ignore examples without recordable results

* temp

* chore: use svg button

* chore: use json5 format for test

* chore: simplify result formatting

* test: add formatting tests

* test: add e2e refresh test

* test: use static test values

* chore: fix regex

* chore: simplify refresh placeholder

* Update cypress/e2e/example-refresh.cy.ts

* fix: handle property after function call

* Apply suggestions from code review

Co-authored-by: Shinigami <[email protected]>

* Apply suggestions from code review

Co-authored-by: Shinigami <[email protected]>

* Apply suggestions from code review

Co-authored-by: Shinigami <[email protected]>

* chore: format

* chore: add comment

---------

Co-authored-by: Shinigami <[email protected]>

2 files changed, 211 insertions, 0 deletions

diff --git a/test/scripts/apidocs/__snapshots__/page.spec.ts.snap b/test/scripts/apidocs/__snapshots__/page.spec.ts.snap
new file mode 100644
index 00000000..4824c101
--- /dev/null
+++ b/test/scripts/apidocs/__snapshots__/page.spec.ts.snap
@@ -0,0 +1,97 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`toRefreshFunction > should handle multiline calls 1`] = `
+"async (): Promise<unknown[]> => {
+  await enableFaker();
+  faker.seed();
+  faker.setDefaultRefDate();
+  const result: unknown[] = [];
+
+  try {
+    result.push(
+      faker.number.int({
+        min: 1,
+        max: 10,
+      })
+    );
+  } catch (error: unknown) {
+    result.push(error instanceof Error ? error.name : 'Error');
+  }
+
+  return result;
+}"
+`;
+
+exports[`toRefreshFunction > should handle multiple calls 1`] = `
+"async (): Promise<unknown[]> => {
+  await enableFaker();
+  faker.seed();
+  faker.setDefaultRefDate();
+  const result: unknown[] = [];
+
+  try {
+    result.push(faker.number.int());
+  } catch (error: unknown) {
+    result.push(error instanceof Error ? error.name : 'Error');
+  }
+
+  try {
+    result.push(faker.number.int());
+  } catch (error: unknown) {
+    result.push(error instanceof Error ? error.name : 'Error');
+  }
+
+  return result;
+}"
+`;
+
+exports[`toRefreshFunction > should handle properties after calls 1`] = `
+"async (): Promise<unknown[]> => {
+  await enableFaker();
+  faker.seed();
+  faker.setDefaultRefDate();
+  const result: unknown[] = [];
+
+  try {
+    result.push(faker.airline.airport().name);
+  } catch (error: unknown) {
+    result.push(error instanceof Error ? error.name : 'Error');
+  }
+
+  return result;
+}"
+`;
+
+exports[`toRefreshFunction > should handle single line calls with semicolon 1`] = `
+"async (): Promise<unknown[]> => {
+  await enableFaker();
+  faker.seed();
+  faker.setDefaultRefDate();
+  const result: unknown[] = [];
+
+  try {
+    result.push(faker.number.int());
+  } catch (error: unknown) {
+    result.push(error instanceof Error ? error.name : 'Error');
+  }
+
+  return result;
+}"
+`;
+
+exports[`toRefreshFunction > should handle single line calls without semicolon 1`] = `
+"async (): Promise<unknown[]> => {
+  await enableFaker();
+  faker.seed();
+  faker.setDefaultRefDate();
+  const result: unknown[] = [];
+
+  try {
+    result.push(faker.number.int());
+  } catch (error: unknown) {
+    result.push(error instanceof Error ? error.name : 'Error');
+  }
+
+  return result;
+}"
+`;
diff --git a/test/scripts/apidocs/page.spec.ts b/test/scripts/apidocs/page.spec.ts
new file mode 100644
index 00000000..00fd4da2
--- /dev/null
+++ b/test/scripts/apidocs/page.spec.ts
@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import { toRefreshFunction } from '../../../scripts/apidocs/output/page';
+import type { RawApiDocsMethod } from '../../../scripts/apidocs/processing/method';
+import type { RawApiDocsSignature } from '../../../scripts/apidocs/processing/signature';
+
+function newTestMethod(
+  signature: Partial<RawApiDocsSignature>
+): RawApiDocsMethod {
+  return {
+    name: 'test',
+    signatures: [
+      {
+        deprecated: 'deprecated',
+        description: 'description',
+        since: 'since',
+        parameters: [],
+        returns: {
+          type: 'simple',
+          text: 'returns',
+        },
+        throws: [],
+        signature: 'signature',
+        examples: [],
+        seeAlsos: [],
+        ...signature,
+      },
+    ],
+    source: {
+      filePath: 'test/page.spec.ts',
+      line: 1,
+      column: 1,
+    },
+  };
+}
+
+describe('toRefreshFunction', () => {
+  it("should return 'undefined' when there are no faker calls", async () => {
+    // given
+    const method = newTestMethod({
+      examples: ['const a = 1;'],
+    });
+
+    // when
+    const result = await toRefreshFunction(method);
+
+    // then
+    expect(result).toBe('undefined');
+  });
+
+  it('should handle single line calls with semicolon', async () => {
+    // given
+    const method = newTestMethod({
+      examples: ['faker.number.int(); // 834135'],
+    });
+
+    // when
+    const result = await toRefreshFunction(method);
+
+    // then
+    expect(result).toMatchSnapshot();
+  });
+
+  it('should handle single line calls without semicolon', async () => {
+    // given
+    const method = newTestMethod({
+      examples: ['faker.number.int() // 834135'],
+    });
+
+    // when
+    const result = await toRefreshFunction(method);
+
+    // then
+    expect(result).toMatchSnapshot();
+  });
+
+  it('should handle multiple calls', async () => {
+    // given
+    const method = newTestMethod({
+      examples: ['faker.number.int()', 'faker.number.int()'],
+    });
+
+    // when
+    const result = await toRefreshFunction(method);
+
+    // then
+    expect(result).toMatchSnapshot();
+  });
+
+  it('should handle multiline calls', async () => {
+    // given
+    const method = newTestMethod({
+      examples: 'faker.number.int({\n  min: 1,\n  max: 10\n})'.split('\n'),
+    });
+
+    // when
+    const result = await toRefreshFunction(method);
+
+    // then
+    expect(result).toMatchSnapshot();
+  });
+
+  it('should handle properties after calls', async () => {
+    // given
+    const method = newTestMethod({
+      examples: ['faker.airline.airport().name'],
+    });
+
+    // when
+    const result = await toRefreshFunction(method);
+
+    // then
+    expect(result).toMatchSnapshot();
+  });
+});