docs: add findings and lessons learned

docs/bugs-found.md

@@ -0,0 +1,105 @@
+# Bugs and Findings
+
+## Purpose
+
+This document captures issues, observations, and testing-related findings discovered while building the DISCOGS-UI automation portfolio project.
+
+Because Discogs is a third-party public website, these findings are documented as observations rather than defects owned by this repository.
+
+---
+
+## Finding 1: Accessibility issue in shared footer navigation
+
+### Area
+
+Accessibility
+
+### Severity
+
+Observed as critical by automated accessibility tooling
+
+### Tool
+
+`@axe-core/playwright`
+
+### Summary
+
+Automated accessibility scans identified an ARIA structure issue in the shared Discogs footer navigation.
+
+### Observed Behavior
+
+The scan reported an `aria-required-children` violation related to a footer menu structure.
+
+### Impact
+
+Users relying on assistive technologies may experience incorrect or confusing navigation semantics.
+
+### Project Decision
+
+Because this issue exists in shared Discogs page chrome and cannot be fixed within this portfolio repository, the finding is documented and the known footer container is excluded from Version 1 automated pass/fail assertions.
+
+---
+
+## Finding 2: Accessibility issue in search clear button
+
+### Area
+
+Accessibility
+
+### Severity
+
+Observed as critical by automated accessibility tooling
+
+### Tool
+
+`@axe-core/playwright`
+
+### Summary
+
+Automated accessibility scans identified a button without a discernible accessible name in the Discogs header/search area.
+
+### Observed Behavior
+
+The scan reported a `button-name` violation for a clear/search-related button.
+
+### Impact
+
+Screen reader users may not understand the purpose of the control.
+
+### Project Decision
+
+Because this issue exists in shared Discogs header UI and cannot be fixed within this portfolio repository, the finding is documented and the known header container is excluded from Version 1 automated pass/fail assertions.
+
+---
+
+## Finding 3: WebKit marketplace access may trigger security challenge
+
+### Area
+
+Cross-browser / CI stability
+
+### Browser
+
+WebKit
+
+### Summary
+
+The marketplace smoke test may encounter a Cloudflare security challenge in WebKit instead of loading the expected Marketplace page.
+
+### Observed Behavior
+
+The page title may display `Just a moment...`, indicating a third-party security challenge.
+
+### Impact
+
+The test cannot reliably validate Marketplace content in WebKit because the expected page is not reached.
+
+### Project Decision
+
+The Marketplace smoke test is skipped in WebKit. Chromium and Firefox continue to validate the Marketplace page.
+
+---
+
+## Notes
+
+No application bugs are claimed as owned defects. Findings are documented to demonstrate QA observation, risk assessment, and practical test design decisions.

docs/lessons-learned.md

@@ -0,0 +1,84 @@
+# Lessons Learned
+
+## Overview
+
+This project provided practical experience building a focused UI automation suite against a real third-party public website.
+
+The most important lesson was that stable automation requires more than writing assertions. It also requires understanding application behavior, external dependencies, browser differences, CI behavior, and realistic test scope.
+
+---
+
+## Lesson 1: Keep Version 1 focused
+
+A smaller, stable test suite is more valuable than a large suite with unstable coverage.
+
+Version 1 intentionally focuses on:
+
+- Public search flows
+- Release/master page navigation
+- Marketplace smoke coverage
+- Negative search behavior
+- Login page validation
+- Unauthenticated account access
+- Accessibility smoke checks
+
+More complex areas, such as authenticated collection testing and performance testing, are deferred as future enhancements.
+
+---
+
+## Lesson 2: Public websites introduce external instability
+
+Because Discogs is a third-party public website, tests may be affected by:
+
+- Security challenges
+- Browser-specific behavior
+- Dynamic content
+- Third-party scripts
+- Page load timing
+- UI changes
+
+The suite was adjusted to avoid relying on full page load events and instead wait for specific page states.
+
+---
+
+## Lesson 3: Assertions should match the test purpose
+
+Several assertions were refined during implementation.
+
+Examples:
+
+- Search validation was changed to verify the URL query parameter and result links instead of relying on broad page text.
+- Marketplace error validation was changed to check specific error indicators instead of scanning all body text.
+- Login page validation focuses on form fields instead of page title text.
+
+These changes made the suite more reliable while preserving meaningful coverage.
+
+---
+
+## Lesson 4: Cross-browser testing requires practical tradeoffs
+
+Running the suite across Chromium, Firefox, and WebKit helped reveal browser-specific behavior.
+
+The Marketplace test is skipped in WebKit because Discogs may return a Cloudflare challenge instead of the Marketplace page.
+
+This skip is documented as an external limitation rather than ignored or hidden.
+
+---
+
+## Lesson 5: Accessibility automation is useful but limited
+
+Automated accessibility scans helped identify critical issues in shared Discogs page chrome.
+
+However, automated scans do not replace a full manual accessibility audit.
+
+Version 1 treats accessibility coverage as smoke-level validation and documents known third-party findings separately.
+
+---
+
+## Lesson 6: AI is useful for drafting, but manual validation is required
+
+AI helped with planning, scaffolding, documentation drafts, and debugging suggestions.
+
+However, every test, selector, assertion, and documentation decision required manual review and local/CI validation.
+
+The final project reflects manual QA judgment, not unreviewed AI output.