From a4ca698f19103b513ceac61a06837ddebbcf7187 Mon Sep 17 00:00:00 2001 From: mikeclark206 Date: Tue, 28 Apr 2026 22:03:46 -0700 Subject: [PATCH] docs: complete README portfolio template alignment --- README.md | 404 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 346 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 57b04b9..abe373c 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,35 @@ # DISCOGS-UI + ![Playwright Tests](https://github.com/mikeclark206/Discogs-UI/actions/workflows/playwright.yml/badge.svg) ![TypeScript](https://img.shields.io/badge/TypeScript-Playwright-blue) ![Test Coverage](https://img.shields.io/badge/Coverage-Smoke%20%7C%20Functional%20%7C%20Integration%20%7C%20Negative%20%7C%20A11y-brightgreen) ![Portfolio Project](https://img.shields.io/badge/Portfolio-QA%20Automation-purple) + Playwright + TypeScript UI automation portfolio project for [Discogs](https://www.discogs.com/). -DISCOGS-UI validates key Discogs user journeys including homepage availability, search, release page navigation, marketplace browsing, login page behavior, negative search handling, unauthenticated account access, and automated accessibility smoke checks. +DISCOGS-UI validates key Discogs user journeys including homepage availability, search, release page navigation, +marketplace browsing, login page behavior, negative search handling, unauthenticated account access, and automated +accessibility smoke checks. + +## Project Summary + +DISCOGS-UI is a QA automation portfolio project built with Playwright, TypeScript, and GitHub Actions. It validates key +Discogs UI workflows through smoke, functional, integration, negative, auth-aware, accessibility, and cross-browser +testing. + +The project demonstrates practical QA skills including test design, UI automation, data-driven testing, CI execution, +test reporting, debugging, documentation, and thoughtful scope control. + +## Why I Chose Discogs + +I chose Discogs for this portfolio project because it reflects both sides of my professional background. Before moving +into tech and QA, I worked in the music industry in several roles, including DJ, radio DJ, journalist, retail marketing +director for a record label, and independent promoter. + +QA has been my professional focus for the last several years, so this project felt like a natural way to combine my +experience in software quality with a long-standing passion for music. Discogs allowed me to build a UI automation +project that feels personally meaningful while still demonstrating practical testing, automation, CLI execution, CI +integration, and documentation skills. --- @@ -13,42 +37,48 @@ DISCOGS-UI validates key Discogs user journeys including homepage availability, This project demonstrates practical QA automation skills through: -- Focused Version 1 test scope -- Page Object Model structure -- Data-driven search testing -- Integration flow validation -- Negative testing -- Accessibility smoke testing -- Cross-browser execution -- GitHub Actions CI -- Playwright HTML reporting -- Documented findings and lessons learned -- Transparent AI-assisted development notes +- Focused Version 1 test scope +- Page Object Model structure +- Data-driven search testing +- Integration flow validation +- Negative testing +- Accessibility smoke testing +- Cross-browser execution +- GitHub Actions CI +- Playwright HTML reporting +- Documented findings and lessons learned +- Transparent AI-assisted development notes + +--- -## Project Purpose +## System Under Test -This project was created as a modern QA portfolio project that combines my professional QA experience with my background in music. +This project tests the public Discogs web application: -Before moving into tech and QA, I worked in the music industry in several roles, including DJ, radio DJ, journalist, retail marketing director for a record label, and independent promoter. Discogs was a natural choice because it connects a personally meaningful music platform with practical UI automation, test design, CI execution, and documentation skills. +- [Discogs](https://www.discogs.com/) + +Version 1 focuses on stable public UI workflows and auth-adjacent behavior that can be validated without modifying user +data. ---- ## Tech Stack -- Playwright -- TypeScript -- Node.js -- GitHub Actions -- `@axe-core/playwright` for accessibility smoke checks -- GitHub Actions artifacts / Playwright HTML report +- Playwright +- TypeScript +- Node.js +- GitHub Actions +- `@axe-core/playwright` for accessibility smoke checks +- GitHub Actions artifacts / Playwright HTML report --- ## Version 1 Goal -Version 1 focuses on building a small, stable, and well-documented UI automation suite that can be run locally and in CI. +Version 1 focuses on building a small, stable, and well-documented UI automation suite that can be run locally and in +CI. -The goal is not to create a large test framework. The goal is to demonstrate practical QA judgment through focused test coverage, maintainable code, meaningful assertions, CI execution, and clear documentation. +The goal is not to create a large test framework. The goal is to demonstrate practical QA judgment through focused test +coverage, maintainable code, meaningful assertions, CI execution, and clear documentation. --- @@ -56,50 +86,50 @@ The goal is not to create a large test framework. The goal is to demonstrate pra ### In Scope -- Homepage smoke validation -- Search functionality using data-driven test cases -- Search result validation for artist, release, and label queries -- Search-to-release/master page integration flow -- Marketplace browse smoke validation -- Negative search validation -- Login page smoke validation -- Negative auth validation for unauthenticated account access -- Automated accessibility smoke checks on selected public pages -- Cross-browser execution with Playwright projects -- CLI execution through npm scripts -- CI execution through GitHub Actions -- Playwright HTML reporting +- Homepage smoke validation +- Search functionality using data-driven test cases +- Search result validation for artist, release, and label queries +- Search-to-release/master page integration flow +- Marketplace browse smoke validation +- Negative search validation +- Login page smoke validation +- Negative auth validation for unauthenticated account access +- Automated accessibility smoke checks on selected public pages +- Cross-browser execution with Playwright projects +- CLI execution through npm scripts +- CI execution through GitHub Actions +- Playwright HTML reporting ### Out of Scope -- Checkout, payment, and seller messaging flows -- Creating, editing, or deleting collection items -- Full OAuth application implementation -- Full authenticated collection flow -- Full WCAG accessibility audit -- Visual regression testing -- Performance testing -- Mobile and responsive testing -- API contract testing +- Checkout, payment, and seller messaging flows +- Creating, editing, or deleting collection items +- Full OAuth application implementation +- Full authenticated collection flow +- Full WCAG accessibility audit +- Visual regression testing +- Performance testing +- Mobile and responsive testing +- API contract testing --- ## Current Test Coverage -| Area | Test Type | Description | -|---|---|---| -| Homepage | Smoke | Validates that the Discogs homepage loads and search is available | -| Search | Functional / Data-driven | Validates search behavior for artist, release, and label queries | -| Search to Release | Integration | Validates that a selected search result opens a matching release or master page | -| Search | Negative | Validates graceful handling of an unlikely search query | -| Marketplace | Smoke | Validates that the marketplace browse page loads successfully | -| Login Page | Smoke / Auth | Validates that the login page loads with expected form controls | -| Account Access | Negative / Auth | Validates that unauthenticated users cannot access account-level areas | -| Public Pages | Accessibility | Runs automated accessibility smoke checks on selected public pages | +| Area | Test Type | Description | +| ----------------- | ------------------------ | ------------------------------------------------------------------------------- | +| Homepage | Smoke | Validates that the Discogs homepage loads and search is available | +| Search | Functional / Data-driven | Validates search behavior for artist, release, and label queries | +| Search to Release | Integration | Validates that a selected search result opens a matching release or master page | +| Search | Negative | Validates graceful handling of an unlikely search query | +| Marketplace | Smoke | Validates that the marketplace browse page loads successfully | +| Login Page | Smoke / Auth | Validates that the login page loads with expected form controls | +| Account Access | Negative / Auth | Validates that unauthenticated users cannot access account-level areas | +| Public Pages | Accessibility | Runs automated accessibility smoke checks on selected public pages | --- -## Project Structure +## Repository Structure ```text DISCOGS-UI/ @@ -129,4 +159,262 @@ DISCOGS-UI/ │ └── smoke/ ├── playwright.config.ts ├── package.json -└── README.md \ No newline at end of file +└── README.md +``` + +--- + +## Getting Started + +### Prerequisites + +To run this project locally, install: + +- Node.js +- npm +- Git + +### Clone the Repository + +```bash +git clone https://github.com/mikeclark206/Discogs-UI.git +cd Discogs-UI +``` + +### Install Dependencies + +```bash +npm install +``` + +### Install Playwright Browsers + +```bash +npx playwright install +``` + +## Running Tests Locally + +Run the full test suite: + +```bash +npm test +``` + +### Run Tests by Browser + +```bash +npm run test:chromium +npm run test:firefox +npm run test:webkit +``` + +### Run Tests by Type + +```bash +npm run test:smoke +npm run test:functional +npm run test:integration +npm run test:negative +npm run test:a11y +``` + +### Open the Playwright HTML Report + +```bash +npm run report +``` + +### Expected Local Result + +The full suite is expected to pass with one intentional skip: + +- Marketplace smoke coverage is skipped in WebKit because Discogs may return a third-party security challenge instead of the expected marketplace page. + +## Environment and Secrets + +Version 1 does not require real user credentials or committed environment files. + +The current suite validates public UI flows, login page behavior, and unauthenticated access handling without using a +real Discogs account. + +Do not commit: + +- `.env` files +- real credentials +- saved authentication state +- generated session files +- Playwright traces or reports that may contain sensitive runtime data + +Authenticated collection coverage is planned as a future enhancement and should use GitHub Actions secrets and +Playwright `storageState` handling. + +## CI Execution and Reporting + +The test suite runs in GitHub Actions on pull requests and updates to the main branch. + +The CI workflow executes Playwright tests across configured browser projects and uploads the Playwright report as a +workflow artifact. + +Reports and artifacts may include: + +- Playwright HTML report +- test traces for failed or retried tests +- screenshots or error context files +- GitHub Actions job logs + +To review CI results: + +1. Open the repository in GitHub. +2. Select the **Actions** tab. +3. Open the latest Playwright workflow run. +4. Review the job logs or download available artifacts. + +This demonstrates that the suite can run outside of a local development environment. + +## Evidence + +Project evidence includes: + +- Passing GitHub Actions workflow runs +- Playwright HTML reports +- Local CLI execution notes +- Documented findings and lessons learned +- Accessibility scan artifacts +- Browser-specific limitation notes + +Supporting documentation is available in the `docs/` folder. + +## Accessibility Testing + +Accessibility checks are implemented with `@axe-core/playwright`. + +Version 1 accessibility testing is intentionally scoped as automated smoke-level coverage. These checks help identify +obvious accessibility issues, but they do not replace a full manual accessibility audit or guarantee WCAG compliance. + +The accessibility suite scans selected public pages, including: + +- Homepage +- Search results page +- Marketplace page + +During implementation, automated scans identified critical accessibility findings in shared Discogs header and footer +page chrome. Because this project tests a third-party public website, those findings are documented separately and +excluded from Version 1 pass/fail assertions. + +More details are available in: + +- `docs/accessibility-notes.md` +- `docs/bugs-found.md` + +## AI Usage + +AI was used as a drafting, planning, and debugging partner during this project. + +AI assisted with: + +- Project framing +- Test strategy brainstorming +- Test scenario drafting +- Page object and test scaffolding +- Documentation structure +- Debugging suggestions +- README and portfolio wording + +All AI-assisted content was manually reviewed before being committed. Final decisions around scope, selectors, +assertions, test data, documentation, and CI behavior were validated manually through local execution and GitHub Actions +runs. + +More details are available in: + +- `docs/ai-usage-notes.md` + +## Documentation + +Additional project documentation is available in the `docs/` folder: + +| Document | Purpose | +| ----------------------------- | ------------------------------------------------------------------- | +| `docs/test-strategy.md` | Defines Version 1 scope, test types, exclusions, and tradeoffs | +| `docs/test-scenarios.md` | Describes the test scenarios covered by the suite | +| `docs/accessibility-notes.md` | Documents accessibility test scope, limitations, and known findings | +| `docs/bugs-found.md` | Captures observed bugs, findings, and third-party limitations | +| `docs/lessons-learned.md` | Summarizes implementation lessons and QA decisions | +| `docs/ai-usage-notes.md` | Explains how AI was used and what was manually reviewed | + +## Key QA Skills Demonstrated + +This project demonstrates: + +- UI automation with Playwright and TypeScript +- Page Object Model test structure +- Smoke testing for critical page availability +- Functional testing for search behavior +- Data-driven testing with reusable test data +- Integration flow validation from search results to release/master pages +- Negative testing for invalid search and unauthenticated access +- Auth-aware test design without exposing credentials +- Automated accessibility smoke testing with axe +- Cross-browser execution across Chromium, Firefox, and WebKit +- GitHub Actions CI integration +- Playwright HTML reporting and test artifacts +- Debugging and stabilization of flaky public-site behavior +- Documentation of findings, limitations, and tradeoffs +- Manual review of AI-assisted work + +## Key Findings and Tradeoffs + +A few important testing decisions were made during implementation: + +- Search assertions were stabilized by validating URL query parameters and result links instead of relying on broad + page text. +- Marketplace error checks were refined to avoid false positives from broad body-content scanning. +- The marketplace smoke test is skipped in WebKit because Discogs may return a third-party security challenge instead + of the expected marketplace page. +- Accessibility scans exclude known shared Discogs header/footer containers from Version 1 pass/fail assertions, while + documenting those findings separately. +- Authenticated collection coverage is deferred because it requires secure credential handling and additional + login-flow stability work. + +Detailed notes are available in: + +- `docs/bugs-found.md` +- `docs/lessons-learned.md` +- `docs/accessibility-notes.md` + +## Future Enhancements + +Potential future enhancements include: + +- Authenticated collection coverage using secure GitHub Actions secrets and Playwright storage state +- Performance testing +- Visual regression testing +- Expanded accessibility testing +- Mobile browser testing using Playwright device emulation +- Responsive layout validation +- API-assisted setup or validation +- Slack notification from CI +- Expanded marketplace coverage + +## Project Status + +Version 1 baseline is complete. + +The current suite includes stable public UI coverage, auth-aware negative testing, accessibility smoke checks, CLI +execution, GitHub Actions CI, Playwright reporting, and portfolio documentation. + +Current status: + +- Local execution supported through npm scripts +- CI execution passing in GitHub Actions +- Public UI flows covered +- Known third-party limitations documented +- Authenticated collection testing deferred to a future enhancement + +## Notes + +This repository is intended as a QA portfolio project and learning artifact. + +The suite is intentionally scoped to a clean Version 1 that is easy to understand, run, review, and extend. The goal is +to demonstrate practical QA judgment through focused coverage, stable automation, clear documentation, and transparent +tradeoff decisions.