autotest/tests/core/documentation.spec.ts

import { test, expect } from '@playwright/test';
import { login, BASE_URL } from '../../helpers/auth';
import { markManual, markWrite } from '../../helpers/manual';
import { attachWriteResult } from '../../helpers/writeResult';

const DOCS_URL = process.env.DOCS_URL ?? `${BASE_URL}/docs`;
const REPO_URL = process.env.REPO_URL ?? `${BASE_URL}/downloads`;

test.describe('core-documentation', () => {
  test('core-documentation-write-release_notes_feature_changes_and_known_issues', async ({ page }, testInfo) => {
    testInfo.annotations.push({ type: 'automationStatus', description: 'automated' });
    markWrite();
    testInfo.annotations.push({ type: 'description', description: 'Navigate to documentation portal, extract and record Release Notes, feature changes, and known issues' });

    const captured: Record<string, unknown> = {};

    await test.step('Navigate to Release Notes page', async () => {
      await page.goto(REPO_URL);
      const rnLink = page.locator('a').filter({ hasText: /release[\s_-]?notes?/i }).first();
      await rnLink.click();
      await page.waitForLoadState('domcontentloaded');
    });

    await test.step('Extract release notes full content', async () => {
      captured['url'] = page.url();
      captured['title'] = await page.title();
      captured['content'] = await page.locator('main, article, .content, body').first().textContent();
    });

    await test.step('Identify new features section', async () => {
      const featuresEl = page.locator('h2, h3').filter({ hasText: /new feature|what.?s new/i }).first();
      if (await featuresEl.count() > 0) {
        captured['featuresSection'] = await featuresEl.textContent();
      }
    });

    await test.step('Identify known issues section', async () => {
      const issuesEl = page.locator('h2, h3').filter({ hasText: /known issue|limitation/i }).first();
      if (await issuesEl.count() > 0) {
        captured['knownIssuesSection'] = await issuesEl.textContent();
      }
    });

    await test.step('Attach captured data to report', async () => {
      await attachWriteResult(testInfo, captured, 'release-notes');
    });

    expect(captured['content']).toBeTruthy();
  });

  test('core-documentation-check-accuracy_installation_and_configuration_guide', async ({ page }, testInfo) => {
    testInfo.annotations.push({ type: 'automationStatus', description: 'manual' });
    testInfo.annotations.push({ type: 'testType', description: 'check' });
    testInfo.annotations.push({ type: 'description', description: 'Verify accuracy of the Installation and Configuration Guide against actual system behaviour' });
    markManual('Requires expert human review: a QA engineer must follow the guide step-by-step on a clean system and validate that each instruction produces the documented result');
    // Manual steps:
    // 1. Open the Installation and Configuration Guide.
    // 2. Provision a clean VM / bare-metal server.
    // 3. Follow each installation step exactly as documented.
    // 4. At each step, verify the actual outcome matches the documented outcome.
    // 5. Note any discrepancy, screenshot or mark the failed step.
    // 6. Document findings in the test run report.
  });

  test('core-documentation-check-accuracy_trouble_shooting_guide', async ({ page }, testInfo) => {
    testInfo.annotations.push({ type: 'automationStatus', description: 'manual' });
    testInfo.annotations.push({ type: 'testType', description: 'check' });
    testInfo.annotations.push({ type: 'description', description: 'Verify the Troubleshooting Guide procedures are accurate and complete' });
    markManual('Requires human expertise: each troubleshooting scenario must be reproduced and the documented resolution steps must be validated against real system behaviour');
    // Manual steps:
    // 1. List all troubleshooting scenarios in the guide.
    // 2. For each scenario, reproduce the described problem condition on a test system.
    // 3. Follow the documented resolution steps.
    // 4. Confirm the issue is resolved as described.
    // 5. Document any steps that are inaccurate, incomplete, or out of date.
  });

  test('core-documentation-write-changed_cli_configuration_commands', async ({ page }, testInfo) => {
    testInfo.annotations.push({ type: 'automationStatus', description: 'automated' });
    markWrite();
    testInfo.annotations.push({ type: 'description', description: 'Navigate to documentation and extract the list of changed CLI configuration commands for this release' });

    const captured: Record<string, unknown> = {};

    await test.step('Navigate to documentation portal', async () => {
      await page.goto(DOCS_URL);
    });

    await test.step('Locate CLI reference or changelog section', async () => {
      const cliLink = page.locator('a').filter({ hasText: /cli|command.?line|reference/i }).first();
      if (await cliLink.count() > 0) {
        await cliLink.click();
        await page.waitForLoadState('domcontentloaded');
      }
      captured['url'] = page.url();
    });

    await test.step('Extract CLI commands listed on the page', async () => {
      const codeBlocks = await page.locator('code, pre, .cli, .command').allTextContents();
      captured['cliCommands'] = codeBlocks;
      captured['totalCommandsFound'] = codeBlocks.length;
    });

    await test.step('Attach captured CLI data to report', async () => {
      await attachWriteResult(testInfo, captured, 'cli-commands');
    });

    expect(Array.isArray(captured['cliCommands'])).toBe(true);
  });
});