Skip to main content

​
Documentation Restructure & Content Plan

Purpose: Master plan for improving documentation quality, depth, and structure. Each section below identifies problems and proposes fixes. Work through sections incrementally — update this file as we go.

​
Keep in Mind (Global Rules)

  • Add contextual callouts between content sections — not just at the end
  • Annotate UI screenshots properly — label elements so users instantly understand the layout
  • Cross-link TestDino resources throughout: sample repo, MCP, changelog, Discord, Slack, social media
  • Every page must pass: Scan Test (10s answer), AI Test (self-contained H2s), Aha! Test (60s understanding)
  • Follow WRITING_GUIDELINES.txt for tone, structure, and component usage

​
Callout Color Schema

ComponentColorIconWhen to Use
<Info>BlueInfo circleWhat you’ll learn (top of page), deeper context, cross-links to deeper guides
<Tip>GreenLightbulbBest practices, shortcuts, helpful advice
<Note>BlueCircle-infoAlternative approaches, optional context, “you can also do X”
<Warning>YellowTriangleGotchas, prerequisites, plan requirements, things that break if skipped
<Danger>RedExclamationData loss, irreversible actions, security risks
<Check>GreenCheckmarkSuccess confirmation, “you’re done” steps
Standard patterns:
  • What you’ll learn → <Info title="What you'll learn"> (blue, first element after frontmatter)
  • Plan requirement → <Warning> (“Available on Pro, Team, and Enterprise plans”)
  • One provider per project → <Note>
  • Cross-link to deeper guide → <Info>
  • Destructive action → <Warning> (“Deleting X removes all Y permanently”)
  • API key security → <Warning> (“Never commit your API key directly”)

​
Target Folder Structure

This is the NEW target nav structure. Updated as we restructure. 
Getting Started
├── index (Home)
├── getting-started
├── CLI Integration
│   ├── cli/overview
│   ├── cli/testdino-playwright-nodejs
│   └── cli/python
├── CI Setup                                    ← NEW group (upload reports from CI)
│   ├── guides/playwright-github-actions          (Tab: GitHub Action | Tab: CLI in YML)
│   ├── guides/playwright-gitlab-ci-setup         (CLI in YML) ← new page, separate from GitLab integration
│   ├── guides/playwright-teamcity                (Tab: Recipe | Tab: CLI in YML)
│   ├── guides/playwright-azure-devops-pipeline   (CLI in YML) ← new page, separate from Azure DevOps extension
│   ├── guides/playwright-circle-ci               ← new page (Tab: Orb | Tab: CLI in YML)
│   └── guides/playwright-amazon-codebuild        ← new page (CLI in YML)
└── faqs

AI
├── ai/overview
├── TestDino MCP
│   ├── mcp/overview
│   ├── mcp/tools-reference
│   └── mcp/troubleshooting
└── ai/playwright-skill

Guides
├── guides/generate-api-keys
├── guides/environment-mapping
├── guides/playwright-flaky-test-detection
├── Debug Failures
│   ├── guides/debug-playwright-test-failures
│   ├── guides/playwright-trace-viewer
│   ├── guides/debug-playwright-failures/visual-evidence
│   └── guides/playwright-error-grouping
├── CI Optimization
│   ├── guides/playwright-ci-optimization
│   └── guides/rerun-failed-playwright-tests
├── guides/playwright-real-time-test-streaming
├── guides/playwright-code-coverage
├── guides/playwright-test-annotations
├── guides/automated-playwright-reports
├── Playwright
│   ├── guides/playwright-visual-testing
│   └── guides/playwright-component-testing
└── Git Provider
    ├── guides/github-status-checks
    └── guides/test-health-badges

Platform
├── Organizations
│   ├── platform/organizations/overview
│   ├── platform/organizations/projects
│   ├── platform/organizations/users-roles
│   ├── Billing & Usage
│   │   ├── platform/billing-and-usage/overview
│   │   ├── platform/billing-and-usage/test-limits
│   │   ├── platform/billing-and-usage/manage-billing
│   │   └── platform/billing-and-usage/invoices
│   └── platform/organizations/settings
├── Dashboard
│   ├── platform/playwright-test-dashboard
│   ├── platform/playwright-qa-dashboard
│   └── platform/playwright-developer-dashboard
├── Pull Requests
│   ├── platform/pull-requests/summary
│   ├── platform/pull-requests/overview
│   ├── platform/pull-requests/timeline
│   └── platform/pull-requests/files-changed
├── Test Runs
│   ├── platform/playwright-test-runs
│   ├── platform/test-runs/playwright-failure-summary
│   ├── platform/playwright-test-runs/specs
│   ├── platform/playwright-test-runs/errors
│   ├── platform/playwright-test-run-history
│   ├── platform/playwright-test-runs/configuration
│   ├── platform/playwright-test-runs/coverage
│   └── platform/playwright-test-runs/ai-insights
├── Test Cases
│   ├── platform/playwright-test-cases
│   ├── platform/playwright-test-case-history
│   └── platform/playwright-test-cases/ai-insights
├── platform/playwright-test-explorer
├── Analytics
│   ├── platform/playwright-test-analytics
│   ├── platform/analytics/playwright-test-health-summary
│   ├── platform/analytics/test-run
│   ├── platform/analytics/test-case
│   ├── platform/analytics/environment
│   ├── platform/analytics/playwright-code-coverage
│   └── platform/analytics/errors
├── platform/playwright-ai-failure-analysis
├── Test Management
│   ├── test-management/playwright-test-case-management
│   ├── test-management/suites
│   ├── Test Case
│   │   ├── test-management/test-case/structure
│   │   ├── test-management/test-case/creating-editing
│   │   └── test-management/test-case/organizing-at-scale
│   └── test-management/import-export
├── platform/project-settings
└── pricing

Resources
├── Integrations
│   ├── integrations/overview
│   ├── CI/CD Integration                           ← renamed from CI/CD
│   │   ├── integrations/ci-cd/github             (app, comments, CI checks, PR sync)
│   │   ├── integrations/playwright-gitlab-ci     (OAuth, comments, MR sync)
│   │   └── integrations/playwright-azure-devops  (VS Marketplace extension, view test data)
│   ├── Issue Tracking
│   │   ├── integrations/jira-playwright-test-failures
│   │   ├── integrations/issue-tracking/linear
│   │   ├── integrations/issue-tracking/asana
│   │   └── integrations/issue-tracking/mon
│   └── Communication
│       ├── integrations/slack-playwright-test-alerts
│       └── integrations/slack/webhook
├── Data Privacy
│   ├── data-privacy/overview
│   ├── data-privacy/access-to-customer-data
│   ├── data-privacy/data-redaction
│   ├── data-privacy/data-retention
│   └── data-privacy/cloud-endpoints
├── support
└── changelog

​
What Moved / Changed

PageFromToNotes
GitHub Actions guideGuides > CI IntegrationGetting Started > CI SetupAdd GitHub Action marketplace tab
TeamCity guideGuides > CI IntegrationGetting Started > CI SetupAlready has Recipe content
Azure DevOps extensionIntegrations > CI/CDIntegrations > CI/CD IntegrationStays as extension page
Azure DevOps pipeline—Getting Started > CI SetupNew page for YML upload
Circle CI—Getting Started > CI SetupNew page (Orb + CLI tabs)
Amazon CodeBuild—Getting Started > CI SetupNew page (CLI in YML)
GitLab CI upload—Getting Started > CI SetupNew page for pipeline upload, separate from GitLab integration
TeamCity integrationIntegrations > CI/CDREMOVEDMerged into TeamCity CI Setup page
”CI Integration” groupGuidesREMOVEDMoved to Getting Started > CI Setup
”CI/CD” groupIntegrationsRenamed → “CI/CD Integration”Only GitHub, GitLab, Azure DevOps extension

​
What’s Not Right

​
1. Getting Started

Problems:
  • Lacks a full picture — user doesn’t know what they’re setting up, where things go, what it does, or why
  • Jumps into steps without showing the end-to-end flow
  • No visual of what a configured project looks like
Fix — Restructure the flow: 
Getting Started with TestDino
 1. Create project on TestDino (after signup + org creation)
 2. Start onboarding flow → get API key
 3. Clone sample repo OR use your own
 4. CLI types:
    - Post-upload vs Realtime streaming (explain difference)
    - Local vs CI/CD (explain when to use which)
 5. Local setup:
    - Install tdpw
    - Configure playwright.config with json/html reporters
      (* show annotated screenshot of full repo config *)
    - Run with CLI command + API key
 6. CI/CD setup:
    - Add yml file (* show annotated screenshot *)
 7. See results in TestDino
The Cursor/Copy prompt should produce a complete ordered guide:
Project creation → API key → Playwright config → YML (if CI/CD) → Run command

​
2. Guides

Problems:
  • TODO: Audit each guide for depth and completeness
Fix: 
TBD — will assess individual guide pages

​
3. Platform

​
3a. Test Management ✅

Problems (were):
  • Docs reflected old test management UI layout
  • Missing pages: Automation view, Bulk Operations, Customization, Key Concepts
  • “Organizing at Scale” mixed suites + tags + bulk into one page
  • “Test Suites” was separate but suites are really just a view
  • No concept of the 3-tab navigation (Suites / Test Cases / Automation)
  • 3-level nesting (Test Management → Test Case → sub-pages)
Final structure (implemented): 
Test Management (10 pages, max 2 levels)
├── Overview — capabilities table, 3 views explained, quick reference
├── Key Concepts — suites, test cases (core/classification/automation fields), steps (Classic + Gherkin), version history, tags
├── Suites — tree view, create/reorder suites, inline test case rows
├── Test Cases
│   ├── List View — search, sort, filter, display columns
│   └── Details Sheet — 4 tabs (Overview, Attachments, History, Linked Tests), properties sidebar, navigation
├── Automation
│   ├── Overview — dual-panel layout, drag-and-drop linking, typical workflow
│   ├── Views — Hierarchy vs Flatten toggle, search/sort/filter per panel, Linked/Unlinked filters
│   └── Suggestions — Auto-Match (AI scoring), Auto-Generate (create from unlinked), recommended workflow
├── Bulk Actions — select (individual/all/suite), bulk edit, delete, print
├── Import & Export — CSV (TestDino/TestRail/Other) + JSON import wizards, 3 export options
└── Customization — feature toggles, enum field customization, custom fields (5 types), field sections

Old pages replaced:
- playwright-test-case-management.mdx → overview.mdx
- suites.mdx → suites.mdx (rewritten)
- test-case/structure.mdx → key-concepts.mdx
- test-case/creating-editing.mdx → test-cases/details-sheet.mdx
- test-case/organizing-at-scale.mdx → split into bulk-actions.mdx + key-concepts (tags)
- import-export.mdx → import-export.mdx (rewritten with JSON support)
Image placeholders: 15 across all pages

​
3b. Analytics

Problems:
  • TODO: Audit for completeness
Fix: 
TBD

​
3c. Test Explorer

Problems:
  • TODO: Audit for completeness
Fix: 
TBD

​
3d. Pull Requests

Problems:
  • TODO: Audit for completeness
Fix: 
TBD

​
3e. Dashboard

Problems:
  • TODO: Audit for completeness
Fix: 
TBD

​
4. Integrations

​
4a. GitHub ✅

Problems (were):
  • Too shallow, no prerequisites, no explanation of what the integration affects
  • Missing: scope/permissions info, two-way sync explanation, PR dashboard connection
  • Duplicate content between sections, confusing branch mapping requirement
  • Comment settings section didn’t match actual UI (default toggles + environment overrides table)
Final structure (implemented): 
GitHub Integration
 1. Opening — installs as GitHub App, bidirectional sync
 2. What the GitHub Integration Does — 6-row feature table (PR comments, commit comments,
    CI checks, PR dashboard, timeline, files changed) with "Where It Appears" column
 3. Prerequisites — account, API key, CLI, GitHub admin access + Tip about plans
 4. Connect TestDino with GitHub
    a. Install the GitHub App (from GitHub marketplace OR TestDino settings, same flow)
       - All repos vs select repos explained
       - Permissions scope table (Actions, Checks, Metadata, Code/Issues/PRs/Workflows)
       - Note: this step only grants access, doesn't connect to project yet
    b. Connect a repository to your TestDino project
       - Redirect flow explained, repo picker, connected state
       - Image placeholder for connected GitHub card
 5. Configure PR Comments (after connection)
    - How to open GitHub Settings panel (⚙️ icon, two tabs)
    - Default comment toggles (PR Comments, Commit Comments)
    - Environment Overrides table (Environment, Branch Patterns, PR, Commits)
    - Tip: overrides are optional, global toggles work without them
 6. Configure CI Checks
    - Settings table (pass rate, mandatory tags, flaky handling, env overrides)
    - Cross-link to full GitHub Status Checks guide
 7. Pull Requests in TestDino
    - Table of 3 tabs (Overview, Timeline, Files Changed) with links
 8. Related CardGroup (status checks, env mapping, PR dashboard, badges)
Images needed:
  • TestDino Settings → Integrations showing connected GitHub card (placeholder in page)

​
4b. GitLab ✅

Problems (were):
  • Very thin — connection steps were one sentence, no detail on OAuth flow or repo selection
  • Comment config was one sentence, didn’t explain actual UI (default toggles + environment overrides)
  • Wrong Warning about branch mapping being mandatory (same issue as GitHub)
  • “CLI Compatibility” section was filler with no value
  • No feature table, no prerequisites, no mention of what syncs into TestDino
  • Didn’t clarify that GitLab has no CI Checks (GitHub-only feature)
Final structure (implemented): 
GitLab Integration
 1. Opening — OAuth connection, bidirectional sync, no pipeline changes needed
    - Note: only one Git provider per project
 2. What the GitLab Integration Does — 6-row feature table (MR comments, commit comments,
    MR state sync, MR dashboard, timeline, files changed)
    - Info: GitLab has no CI Checks, link to GitHub for that
 3. Prerequisites — account, API key, CLI, GitLab Maintainer/Owner access
 4. Connect TestDino with GitLab
    a. Authorize TestDino in GitLab (OAuth flow from TestDino settings)
       - <image: GitLab OAuth authorization screen>
       - Note: this only grants access, doesn't connect to project yet
    b. Connect a repository to your TestDino project
       - <image: TestDino repo selection screen for GitLab>
       - <image: GitLab card in connected state>
 5. Configure MR Comments (after connection)
    - Default toggles (MR Comments, Commit Comments)
    - Environment Overrides table (Environment, Branch Patterns, MR, Commits)
    - <image: GitLab Settings panel with comment toggles and overrides>
    - Tip: overrides are optional
 6. Merge Requests in TestDino
    - Table of 3 tabs (Overview, Timeline, Files Changed) with links
    - MR state sync explanation
 7. Related CardGroup (GitHub, env mapping, PR dashboard, CLI)
Images needed (4 placeholders in page):
  • GitLab OAuth authorization screen
  • TestDino repo selection screen for GitLab repos
  • GitLab card in connected state with repo name and gear icon
  • GitLab Settings panel showing comment toggles and environment overrides

​
4c. CI/CD Nav Restructure ✅

Problems (were):
  • CI upload guides and app integrations mixed under the same “CI/CD” group in Integrations
  • TeamCity appeared in both Guides > CI Integration AND Integrations > CI/CD (duplicate)
  • No distinction between “upload results from CI” and “connect an app that syncs data”
  • Circle CI and Amazon CodeBuild not documented at all
  • Azure DevOps page only covered the extension, not pipeline upload
Fix — Split by purpose:
  • Getting Started > CI Setup = upload-only guides (part of onboarding flow)
    • GitHub Actions (Tab: GitHub Action marketplace module | Tab: CLI in YML)
    • GitLab CI (CLI in YML)
    • TeamCity (Tab: Recipe | Tab: CLI in YML)
    • Azure DevOps Pipeline (CLI in YML)
    • Circle CI (Tab: TestDino Orb | Tab: CLI in YML) ← new page
    • Amazon CodeBuild (CLI in YML) ← new page
  • Integrations > CI/CD Integration = apps/OAuth that sync data bidirectionally
    • GitHub (app, comments, CI checks, PR sync)
    • GitLab (OAuth, comments, MR sync)
    • Azure DevOps Extension (VS Marketplace, view test data in Azure DevOps)
  • Remove “CI Integration” group from Guides entirely
  • Remove duplicate TeamCity from Integrations > CI/CD

​
4d. Issue Tracking (Jira, Linear, Asana) ✅

Problems (were):
  • No prerequisites, no connection steps (one bullet each)
  • No explanation of where the “Raise Bug” button appears in the UI
  • “Why this helps” sections were marketing fluff
  • No manage/disconnect section
  • Connection scope (user-level) not mentioned
  • Empty CardGroup descriptions
Final structure (implemented, same for all three): 
1. What you'll learn
2. Opening — what it does, user-level scope, plan requirement
3. Video demo
4. Prerequisites — TestDino project, tool account, target project/workspace
5. Connect [Tool] — 3 steps: open integrations → authorize OAuth → configure defaults (image placeholders)
6. Create Bug Report — where to find button, form walkthrough with screenshot
7. What TestDino Pre-fills — table (kept from original, already good)
8. After Creating — confirmation details
9. Manage the Integration — sync/disconnect/change defaults table
10. Troubleshooting — 4 accordions (fields missing, auth expired with auto-refresh note, button not visible, issue missing data)
11. Related CardGroup with descriptions

​
4e. Communication (Slack App, Slack Webhook) ✅

Problems (were):
  • Slack Webhook had no steps to generate the webhook URL in Slack (only pasting in TestDino)
  • Slack App missing: test button info, private channel setup steps, channel list refresh behavior
  • No troubleshooting on either page
Fixes applied:
  • Slack App: added image placeholders (5), troubleshooting with private channel accordion (Integrations tab → Add App → search TestDino), test button mentions
  • Slack Webhook: full step-by-step for generating webhook in Slack (api.slack.com → Create App → Incoming Webhooks), image placeholders (4), troubleshooting (3 accordions)

​
4f. Other Integrations

Problems:
  • TODO: monday page needs audit (already has widget + issue creation content)
Fix: 
TBD — monday page content exists but needs quality pass

​
Progress Tracker

SectionStatusNotes
Getting Started📋 PlannedFlow restructure defined above
Guides⏳ Not startedNeeds audit
Platform — Test Management✅ DoneFull restructure: 10 pages, flat nav (max 2 levels). Overview, Key Concepts, Suites, Test Cases (List View + Details Sheet), Automation (Overview + Views + Suggestions), Bulk Actions, Import & Export, Customization. 15 image placeholders.
Platform — Analytics⏳ Not startedNeeds audit
Platform — Test Explorer⏳ Not startedNeeds audit
Platform — Pull Requests⏳ Not startedNeeds audit
Platform — Dashboard⏳ Not startedNeeds audit
Integrations — GitHub✅ DoneFull rewrite: bidirectional sync, permissions scope table, two-step connection flow, comment settings matching actual UI, PR dashboard section. 1 image placeholder remaining.
Integrations — GitLab✅ DoneFull rewrite: OAuth flow, feature table (no CI Checks), MR comment config with toggles + overrides, MR dashboard section. 4 image placeholders.
CI/CD Nav Restructure✅ Donedocs.json updated: CI Setup under Getting Started, CI/CD Integration under Integrations
CI Setup — GitHub Actions⏳ Not startedMove from Guides, add GitHub Action marketplace tab
CI Setup — GitLab CI✅ DoneNew page with basic + sharded config, pipeline execution + TestDino result images
CI Setup — TeamCity⏳ Not startedMove from Guides, merge with Integrations duplicate
CI Setup — Azure DevOps Pipeline✅ DoneNew page with basic + sharded config, secret variable setup, pipeline + TestDino images
CI Setup — CircleCI✅ DoneNew page with Orb (4 examples + params table) + CLI tabs, sharded config, troubleshooting
CI Setup — Amazon CodeBuild⏳ Not startedNew page (CLI in YML)
Integrations — Azure DevOps Ext✅ DoneUpdated: short description, what you’ll learn, PAT terminology fixed in troubleshooting
Integrations — Overview✅ DoneRewritten: intro, card grid, scope table, category tables, Slack App detail, no TeamCity
Integrations — Jira✅ DoneFull rewrite: prerequisites, 3-step connection, bug report walkthrough, manage table, troubleshooting
Integrations — Linear✅ DoneFull rewrite: same structure as Jira, Linear-specific fields
Integrations — Asana✅ DoneFull rewrite: same structure as Jira, Asana-specific fields
Integrations — Slack App✅ DoneAdded: image placeholders, private channel steps, test button, troubleshooting
Integrations — Slack Webhook✅ DoneAdded: full webhook generation steps, image placeholders, troubleshooting
Integrations — monday⏳ Not startedNeeds quality audit (content exists)