Skip to content

Ship: docs: add test mining implementation planning set #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kalen-releasedgroup merged 1 commit into from
Apr 23, 2026
Merged

Ship: docs: add test mining implementation planning set #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
308 changes: 154 additions & 154 deletions AGENTS.md
View file
Open in desktop

Large diffs are not rendered by default.

176 changes: 88 additions & 88 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,88 +1,88 @@
# Test Mining Platform

This repository is being used to build a C#-based semantic test mining platform that records browser interactions, converts them into structured scenarios, and generates maintainable Playwright tests with replay and healing support.

The current source of truth for the planned product is [docs/requirements.md](/mnt/c/Users/kenne/Desktop/ReleasedGroup/2EndSquaredTesting/docs/requirements.md). The concept document that informed it is [docs/concept.md](/mnt/c/Users/kenne/Desktop/ReleasedGroup/2EndSquaredTesting/docs/concept.md).

## Product Summary

The application described in this repository is not intended to be a raw click recorder. It is intended to be a semantic test mining and stabilisation platform that:

- records real user workflows in a browser
- captures DOM, accessibility, navigation, and runtime context around meaningful actions
- transforms raw events into structured, intent-rich scenarios
- infers resilient locators, variable data strategies, and outcome-oriented assertions
- generates readable C# Playwright tests and supporting helpers
- replays generated scenarios and provides deterministic healing when selectors drift

The core design rule is that structured scenarios are the source of truth. Generated code is a derived artefact and must remain reproducible from scenario data and generation settings.

## Intended Stack

The requirements currently define this implementation model:

- Backend: ASP.NET Core
- Frontend: Blazor Server
- Database: PostgreSQL or SQL Server
- Browser automation: Microsoft.Playwright for .NET
- Code generation: Roslyn or Scriban templates
- Desktop packaging later: .NET MAUI Hybrid or Electron wrapper if needed

## Planned Capabilities

The platform is expected to include these major areas:

- Recording engine for guided browser-session capture
- DOM and accessibility analysis
- Scenario authoring and timeline review
- Locator ranking and assertion suggestion
- C# Playwright code generation
- Replay diagnostics
- Deterministic healing workflows
- Persistent storage for sessions, scenarios, artefacts, and replay history
- Administrative configuration for environments, browser settings, and generation defaults

## Repository Guidance

This repository currently contains existing Symphony-related files and scaffolding. Those files are being retained in the repository because Symphony is a tool used within this project context.

Symphony guidance for users and agents:

- Treat Symphony-related files as retained tool files, not as the application being described in `docs/requirements.md`.
- Do not rewrite, repurpose, or delete Symphony files unless a task explicitly asks for Symphony/tooling work.
- Keep Symphony files in the repository even while building the new application.
- New product work should align to `docs/requirements.md`, not the legacy Symphony README content that previously occupied this file.

Examples of retained Symphony-related content include:

- `SPEC.md`
- `IMPLEMENTATION_PLAN.md`
- `WORKFLOW.md`
- `src/Symphony.*`
- `tests/Symphony.*`
- `symphony_docs/`

## Expected Solution Direction

A likely repository shape for the new application is described in the requirements document and includes logical areas such as:

- host and Blazor Server UI
- core domain and scenario contracts
- recording and Playwright orchestration
- analysis and inference
- code generation
- replay and healing
- persistence and artefact storage
- automated tests

## Current Status

The repository is in a planning and transition stage:

- the requirements specification exists in `docs/requirements.md`
- the concept source exists in `docs/concept.md`
- the new application implementation may coexist with retained Symphony tooling content during development

## Working Rule

If there is a conflict between older Symphony-oriented repository documentation and the new product direction, treat `docs/requirements.md` as the authoritative description of the application to be built, while still preserving Symphony-related files as tooling assets unless explicitly instructed otherwise.
# Test Mining Platform
This repository is being used to build a C#-based semantic test mining platform that records browser interactions, converts them into structured scenarios, and generates maintainable Playwright tests with replay and healing support.
The current source of truth for the planned product is [docs/requirements.md](/mnt/c/Users/kenne/Desktop/ReleasedGroup/2EndSquaredTesting/docs/requirements.md). The concept document that informed it is [docs/concept.md](/mnt/c/Users/kenne/Desktop/ReleasedGroup/2EndSquaredTesting/docs/concept.md).
## Product Summary
The application described in this repository is not intended to be a raw click recorder. It is intended to be a semantic test mining and stabilisation platform that:
- records real user workflows in a browser
- captures DOM, accessibility, navigation, and runtime context around meaningful actions
- transforms raw events into structured, intent-rich scenarios
- infers resilient locators, variable data strategies, and outcome-oriented assertions
- generates readable C# Playwright tests and supporting helpers
- replays generated scenarios and provides deterministic healing when selectors drift
The core design rule is that structured scenarios are the source of truth. Generated code is a derived artefact and must remain reproducible from scenario data and generation settings.
## Intended Stack
The requirements currently define this implementation model:
- Backend: ASP.NET Core
- Frontend: Blazor Server
- Database: PostgreSQL or SQL Server
- Browser automation: Microsoft.Playwright for .NET
- Code generation: Roslyn or Scriban templates
- Desktop packaging later: .NET MAUI Hybrid or Electron wrapper if needed
## Planned Capabilities
The platform is expected to include these major areas:
- Recording engine for guided browser-session capture
- DOM and accessibility analysis
- Scenario authoring and timeline review
- Locator ranking and assertion suggestion
- C# Playwright code generation
- Replay diagnostics
- Deterministic healing workflows
- Persistent storage for sessions, scenarios, artefacts, and replay history
- Administrative configuration for environments, browser settings, and generation defaults
## Repository Guidance
This repository currently contains existing Symphony-related files and scaffolding. Those files are being retained in the repository because Symphony is a tool used within this project context.
Symphony guidance for users and agents:
- Treat Symphony-related files as retained tool files, not as the application being described in `docs/requirements.md`.
- Do not rewrite, repurpose, or delete Symphony files unless a task explicitly asks for Symphony/tooling work.
- Keep Symphony files in the repository even while building the new application.
- New product work should align to `docs/requirements.md`, not the legacy Symphony README content that previously occupied this file.
Examples of retained Symphony-related content include:
- `SPEC.md`
- `IMPLEMENTATION_PLAN.md`
- `WORKFLOW.md`
- `src/Symphony.*`
- `tests/Symphony.*`
- `symphony_docs/`
## Expected Solution Direction
A likely repository shape for the new application is described in the requirements document and includes logical areas such as:
- host and Blazor Server UI
- core domain and scenario contracts
- recording and Playwright orchestration
- analysis and inference
- code generation
- replay and healing
- persistence and artefact storage
- automated tests
## Current Status
The repository is in a planning and transition stage:
- the requirements specification exists in `docs/requirements.md`
- the concept source exists in `docs/concept.md`
- the new application implementation may coexist with retained Symphony tooling content during development
## Working Rule
If there is a conflict between older Symphony-oriented repository documentation and the new product direction, treat `docs/requirements.md` as the authoritative description of the application to be built, while still preserving Symphony-related files as tooling assets unless explicitly instructed otherwise.
35 changes: 35 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Test Mining Platform Documentation Index

This folder now contains the planning and specification documents for the new test mining platform described by [requirements.md](./requirements.md).

## Core Source Documents

- [Requirements Specification](./requirements.md)
- [Concept Document](./concept.md)

## Planning Documents

- [Technical Specification](./technical-specification.md)
- [UI/UX Plan](./ui-ux-plan.md)
- [Security Plan](./security-plan.md)
- [Testing Plan](./testing-plan.md)
- [Implementation Roadmap](./implementation-roadmap.md)
- [Requirements Traceability Matrix](./requirements-traceability-matrix.md)

## Recommended Reading Order

1. `requirements.md`
2. `technical-specification.md`
3. `ui-ux-plan.md`
4. `security-plan.md`
5. `testing-plan.md`
6. `implementation-roadmap.md`
7. `requirements-traceability-matrix.md`

## Usage Guidance

- Treat `requirements.md` as the source of truth.
- Use the technical specification and roadmap to plan implementation slices.
- Use the UI/UX, security, and testing plans as non-optional design constraints.
- Use the traceability matrix to connect future code, tests, ADRs, and pull requests back to requirements.
- Treat all planning documents as subordinate to `requirements.md`; if a planning document and the requirements differ, update the planning document.
169 changes: 169 additions & 0 deletions docs/implementation-roadmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
# Test Mining Platform Implementation Roadmap

## 1. Purpose

This roadmap converts the delivery phasing in [docs/requirements.md](./requirements.md) Section 18 into implementation slices that fit the repository and reduce delivery risk.

## 2. Roadmap Principles

1. Build vertical slices, not disconnected layers.
2. Preserve `Symphony.*` tooling assets untouched unless explicitly requested.
3. Prove the canonical `Scenario` workflow early.
4. Treat security and observability as phase-entry requirements, not polish.
5. Keep each slice traceable to `FR-*` requirements and acceptance criteria.

## 3. Foundation Track

This track should start before Phase 1 feature depth expands.

Deliverables:

- `TestMining.Platform.*` project scaffolding
- PostgreSQL persistence bootstrap and migrations pipeline
- authentication shell and role model
- internal API versioning convention
- SignalR infrastructure
- artefact storage abstraction
- fixture app test harness
- baseline observability and audit primitives
- ADRs for generator choice, authentication provider, replay execution boundary, and draft persistence shape

Requirement anchors:

- Sections 6, 10, 11, 12.1, 13, 14, 16, 17, 22

## 4. Phase 1: Core Proof

Objective:

Prove the end-to-end path from recording to generated code to replay on a simple fixture application.

Suggested slices:

1. Recording session creation plus allow-list validation
2. Playwright browser launch and recorder injection
3. Meaningful event capture for navigation, click, fill, select, and checkbox
4. Incremental recording persistence
5. Initial timeline UI with human-readable steps
6. Locator candidate creation and ranking
7. Draft scenario editing and immutable version creation
8. Deterministic C# generator for one profile
9. Basic replay execution and step-level result reporting

Phase 1 exit should match Section 18.5 Phase 1 exit criteria.

Phase 1 is not complete unless URL allow-list enforcement and encryption of stored auth/session material are demonstrably working, because they are part of the stated exit criteria rather than optional hardening.

## 5. Phase 2: Robustness

Objective:

Increase semantic quality and diagnostic usefulness without changing the core source-of-truth model.

Suggested slices:

1. assertion suggestion engine
2. variable classification editing
3. fuzzy/resilient assertion strategies
4. scoped locator support
5. replay failure screenshots
6. richer replay diagnostics packaging
7. confidence explanation surfaces

Requirement anchors:

- `FR-INF-006` through `FR-INF-009`
- `FR-AUTH-003`, `FR-AUTH-004`
- `FR-REP-002`, `FR-REP-003`

## 6. Phase 3: Product Hardening

Objective:

Harden the system for multi-user and longer-lived operational use.

Suggested slices:

1. authentication bootstrap modes
2. export packaging workflow
3. trace viewer integration
4. healing approval workflow and version lineage
5. scenario history and diff views
6. retention cleanup scheduling and admin controls

Requirement anchors:

- `FR-ADM-002`
- `FR-HEAL-001` through `FR-HEAL-005`
- Sections 7.4, 12.7, 16.4

## 7. Phase 4: AI Assistance

Objective:

Add advisory AI features without weakening deterministic execution or approval rules.

Suggested slices:

1. AI-assisted naming suggestions
2. AI-assisted assertion suggestion refinement
3. AI-assisted healing proposal augmentation
4. page object refactoring suggestions

Guardrails:

- feature flagged
- disabled by default
- advisory only
- deterministic evidence always shown
- no mutation of persisted scenarios without the same approval and traceability rules required for deterministic healing

## 8. Cross-Cutting Backlog

These items should run across phases:

- security hardening and audits
- performance instrumentation
- accessibility improvements in Blazor UI
- documentation updates
- CI pipeline maturation

## 9. Recommended Work Breakdown Structure

Suggested implementation order:

1. scaffold projects and shared contracts
2. establish persistence, auth shell, and audit primitives
3. build recording pipeline
4. build timeline authoring and versioning
5. build generation
6. build replay
7. add diagnostics depth
8. add healing workflow
9. add advanced admin and AI-adjacent features

## 10. Dependencies and Risks

Key dependencies:

- stable fixture applications for test coverage
- Playwright recorder script build strategy
- PostgreSQL dev/test environment availability
- final authentication provider selection

Key risks:

- over-investing in raw recording before scenario editing is solid
- leaking sensitive data through early diagnostics
- making generator output non-deterministic
- coupling replay too tightly to generated code instead of scenario model

## 11. Milestone Definition

Each roadmap slice should only be closed when it has:

- linked requirement IDs
- passing automated coverage
- documented artefact/security impact
- structured logs and diagnostics where applicable
- no mutation of retained `Symphony.*` assets
Loading
Loading