diff --git a/docs/get-started/real-world-examples/cli-installation.mdx b/docs/get-started/real-world-examples/cli-installation.mdx new file mode 100644 index 00000000..055530a5 --- /dev/null +++ b/docs/get-started/real-world-examples/cli-installation.mdx @@ -0,0 +1,163 @@ +--- +sidebar_label: CLI installation guide +description: Test command-line tool installation guides with version checks and functionality validation +--- + +# Testing a CLI installation guide + +## When to use this + +Use this approach when you document command-line tools that users install via package managers like npm, pip, or apt. Installation guides must have accurate commands that work across different environments. + +## What this tests + +- Installation command executes without errors +- Installed tool is accessible from the command line +- Version output matches expectations +- Basic functionality works after installation + +## Prerequisites + +- [Doc Detective installed](/docs/get-started/installation) +- Access to run shell commands on your system +- The CLI tool you're testing (or a test environment) + +## Complete example + +```json title="cli-installation.spec.json" +{ + "tests": [ + { + "steps": [ + { + "description": "Install the CLI tool using npm", + "runShell": { + "command": "npm install -g doc-detective", + "exitCodes": [0] + } + }, + { + "description": "Verify installation by checking the version", + "runShell": { + "command": "doc-detective --version", + "stdio": "/^\\d+\\.\\d+\\.\\d+/" + } + }, + { + "description": "Test basic functionality with help command", + "runShell": { + "command": "doc-detective --help", + "stdio": "Usage:" + } + }, + { + "description": "Run a simple test to validate the tool works", + "runShell": { + "command": "echo '{\"tests\": [{\"steps\": [{\"checkLink\": \"https://example.com\"}]}]}' > /tmp/test.json && doc-detective --input /tmp/test.json", + "exitCodes": [0] + } + } + ] + } + ] +} +``` + +## Expected output + +When the test passes, you should see output indicating all steps completed successfully: + +```json +{ + "summary": { + "steps": { + "pass": 4, + "fail": 0 + } + } +} +``` + +Each shell command executes without errors, version output matches the expected pattern, and the basic functionality test runs successfully. + +## Common variations + +**Test installation with version pinning:** + +```json +{ + "description": "Install a specific version", + "runShell": { + "command": "npm install -g doc-detective@3.0.0", + "exitCodes": [0] + } +} +``` + +**Test platform-specific installation:** + +Use the [`runOn`](/docs/references/schemas/test#fields) property to run different commands based on the platform: + +```json +{ + "tests": [ + { + "runOn": [ + { + "platforms": ["linux", "mac"] + } + ], + "steps": [ + { + "description": "Install on Unix-like systems", + "runShell": "sudo apt-get install -y your-tool" + } + ] + }, + { + "runOn": [ + { + "platforms": ["windows"] + } + ], + "steps": [ + { + "description": "Install on Windows", + "runShell": "choco install your-tool" + } + ] + } + ] +} +``` + +**Validate command output with variables:** + +```json +{ + "steps": [ + { + "description": "Get installed version", + "runShell": { + "command": "doc-detective --version", + "stdio": "/.+/" + }, + "variables": { + "INSTALLED_VERSION": "$$stdio.stdout" + } + }, + { + "description": "Echo the captured version", + "runShell": { + "command": "echo Installed version: $INSTALLED_VERSION" + } + } + ] +} +``` + +## Next steps + +- Learn more about the [`runShell`](/docs/get-started/actions/runShell) action +- Explore [test contexts](/docs/get-started/config/contexts) for cross-platform testing +- Review [variables](/docs/get-started/actions/loadVariables) for capturing command output diff --git a/docs/get-started/real-world-examples/code-examples.mdx b/docs/get-started/real-world-examples/code-examples.mdx new file mode 100644 index 00000000..6c312bc3 --- /dev/null +++ b/docs/get-started/real-world-examples/code-examples.mdx @@ -0,0 +1,156 @@ +--- +sidebar_label: Code examples +description: Test code examples across multiple programming languages with validation +--- + +# Testing code examples with multiple languages + +## When to use this + +Use this approach when your SDK or API documentation provides code examples in multiple programming languages. Each language's examples must be syntactically correct and produce expected results. + +## What this tests + +- Code examples execute without errors +- Output matches documentation +- Dependencies are available +- Cross-language consistency + +## Prerequisites + +- [Doc Detective installed](/docs/get-started/installation) +- Programming language runtimes installed (Python, Node.js, etc.) +- Required libraries/packages for code examples + +## Complete example + +```json title="code-examples.spec.json" +{ + "tests": [ + { + "steps": [ + { + "description": "Test Python example - Hello World", + "runCode": { + "language": "python", + "code": "print('Hello from Python!')", + "stdio": "Hello from Python!" + } + }, + { + "description": "Test Python example - API request", + "runCode": { + "language": "python", + "code": "import json\ndata = {'status': 'success', 'message': 'API working'}\nprint(json.dumps(data))", + "stdio": "/.*success.*/" + } + }, + { + "description": "Test JavaScript example - Hello World", + "runCode": { + "language": "javascript", + "code": "console.log('Hello from Node.js!');", + "stdio": "Hello from Node.js!" + } + }, + { + "description": "Test JavaScript example - JSON parsing", + "runCode": { + "language": "javascript", + "code": "const data = {status: 'success', message: 'API working'}; console.log(JSON.stringify(data));", + "stdio": "/.*success.*/" + } + }, + { + "description": "Test Bash example - environment check", + "runCode": { + "language": "bash", + "code": "echo \"Shell: $SHELL\" && echo \"Path configured\"", + "stdio": "/Path configured/" + } + } + ] + } + ] +} +``` + +## Expected output + +When the test passes, you should see: + +```json +{ + "summary": { + "steps": { + "pass": 5, + "fail": 0 + } + } +} +``` + +Each code example executes in its respective language runtime and produces the expected output. + +## Common variations + +**Test code with dependencies:** + +```json +{ + "steps": [ + { + "description": "Install required package", + "runShell": { + "command": "pip install requests" + } + }, + { + "description": "Test code using the package", + "runCode": { + "language": "python", + "code": "import requests\nresponse = requests.get('https://httpbin.org/status/200')\nprint(response.status_code)", + "stdio": "200" + } + } + ] +} +``` + +**Validate error handling:** + +```json +{ + "description": "Test Python exception handling", + "runCode": { + "language": "python", + "code": "try:\n x = 1 / 0\nexcept ZeroDivisionError:\n print('Caught division by zero')", + "stdio": "Caught division by zero" + } +} +``` + +**Test multi-line code blocks:** + +```json +{ + "description": "Test Python function definition", + "runCode": { + "language": "python", + "code": [ + "def greet(name):", + " return f'Hello, {name}!'", + "", + "result = greet('Developer')", + "print(result)" + ], + "stdio": "Hello, Developer!" + } +} +``` + +## Next steps + +- Learn more about the [`runCode`](/docs/get-started/actions/runCode) action +- Explore [`runShell`](/docs/get-started/actions/runShell) for managing dependencies +- Review [variables](/docs/get-started/actions/loadVariables) for sharing data between steps diff --git a/docs/get-started/real-world-examples/documentation-links.mdx b/docs/get-started/real-world-examples/documentation-links.mdx new file mode 100644 index 00000000..fd9e07f2 --- /dev/null +++ b/docs/get-started/real-world-examples/documentation-links.mdx @@ -0,0 +1,137 @@ +--- +sidebar_label: Documentation links +description: Test documentation links to validate internal and external references +--- + +# Testing documentation links + +## When to use this + +Use this approach when your documentation contains many links to other pages, external resources, or API endpoints. Broken links frustrate users and damage credibility. Regular link checking ensures all references remain valid. + +## What this tests + +- Internal documentation links are valid +- External resource links are accessible +- API endpoint URLs return expected status codes +- Redirects work correctly + +## Prerequisites + +- [Doc Detective installed](/docs/get-started/installation) +- Network access to the links you're testing + +## Complete example + +```json title="link-checking.spec.json" +{ + "tests": [ + { + "steps": [ + { + "description": "Check main documentation homepage", + "checkLink": "https://doc-detective.com" + }, + { + "description": "Check getting started guide", + "checkLink": "https://doc-detective.com/docs/get-started/installation" + }, + { + "description": "Check API reference with multiple acceptable status codes", + "checkLink": { + "url": "https://doc-detective.com/docs/category/actions", + "statusCodes": [200, 301, 302] + } + }, + { + "description": "Check external GitHub repository", + "checkLink": "https://github.com/doc-detective/doc-detective" + }, + { + "description": "Check NPM package page", + "checkLink": { + "url": "https://www.npmjs.com/package/doc-detective", + "statusCodes": [200] + } + }, + { + "description": "Check external API endpoint", + "checkLink": { + "url": "https://api.github.com", + "statusCodes": [200] + } + } + ] + } + ] +} +``` + +## Expected output + +When the test passes, you should see: + +```json +{ + "summary": { + "steps": { + "pass": 6, + "fail": 0 + } + } +} +``` + +All links return acceptable HTTP status codes, indicating they're accessible and valid. + +## Common variations + +**Check links with authentication:** + +```json +{ + "description": "Check protected API endpoint", + "checkLink": { + "url": "https://api.example.com/protected", + "statusCodes": [200, 401] + } +} +``` + +**Accept redirects as valid:** + +```json +{ + "description": "Check URL that may redirect", + "checkLink": { + "url": "https://example.com/old-page", + "statusCodes": [200, 301, 302, 307, 308] + } +} +``` + +**Batch check multiple links:** + +Create a test with many steps to check all your documentation links at once: + +```json +{ + "tests": [ + { + "steps": [ + {"checkLink": "https://example.com/page1"}, + {"checkLink": "https://example.com/page2"}, + {"checkLink": "https://example.com/page3"}, + {"checkLink": "https://example.com/page4"}, + {"checkLink": "https://example.com/page5"} + ] + } + ] +} +``` + +## Next steps + +- Learn more about the [`checkLink`](/docs/get-started/actions/checkLink) action +- Explore [troubleshooting certificate issues](/docs/get-started/actions/checkLink#checklink-fails-due-to-unrecognized-certificates) +- Review [configuration options](/docs/references/schemas/config) for setting a default origin diff --git a/docs/get-started/real-world-examples/overview.mdx b/docs/get-started/real-world-examples/overview.mdx new file mode 100644 index 00000000..0b049406 --- /dev/null +++ b/docs/get-started/real-world-examples/overview.mdx @@ -0,0 +1,42 @@ +--- +sidebar_label: Overview +description: Complete, copy-paste-ready examples for common documentation testing scenarios +--- + +# Real-world examples + +This guide provides complete, working examples for common documentation testing scenarios. Each example is ready to copy, paste, and adapt to your needs. + +Use these examples to quickly find a relevant scenario, understand how Doc Detective solves it, and customize the solution for your documentation. + +## What you'll find here + +Each scenario includes: + +- **When to use**: Description of the documentation challenge +- **What this tests**: Key validation points +- **Prerequisites**: What you need before starting +- **Complete example**: Full test specification with inline comments +- **Expected output**: What success looks like +- **Common variations**: Ways to adapt the example +- **Next steps**: Links to related topics + +## Available scenarios + +- [Testing a CLI installation guide](cli-installation) - Validates package installation commands, version checks, and basic functionality +- [Testing a REST API tutorial](rest-api) - Demonstrates full CRUD workflows with request/response validation +- [Validating screenshots in a UI walkthrough](ui-screenshots) - Shows automated screenshot capture and visual comparison +- [Testing a multi-step user workflow](user-workflow) - End-to-end form filling and registration flow validation +- [Testing code examples with multiple languages](code-examples) - Multi-language code validation across Python, JavaScript, and Bash +- [Testing documentation links](documentation-links) - Link checking for internal and external documentation references + +## What's next + +Now that you've seen real-world examples, you can: + +- **Adapt these examples** to your specific documentation needs +- **Combine scenarios** to create comprehensive test suites +- **Automate testing** with CI/CD integration +- **Explore advanced features** in the [actions reference](/docs/category/actions) + +Have questions or need help? Check out the [resources](/docs/get-started/resources) page or visit our [GitHub repository](https://github.com/doc-detective/doc-detective). diff --git a/docs/get-started/real-world-examples/rest-api.mdx b/docs/get-started/real-world-examples/rest-api.mdx new file mode 100644 index 00000000..11c7e14c --- /dev/null +++ b/docs/get-started/real-world-examples/rest-api.mdx @@ -0,0 +1,189 @@ +--- +sidebar_label: REST API tutorial +description: Test REST API documentation with request/response validation and variable chaining +--- + +# Testing a REST API tutorial + +## When to use this + +Use this approach when you document REST APIs with curl commands or code examples that demonstrate endpoint usage. API documentation must stay synchronized with actual API behavior, including request/response formats and status codes. + +## What this tests + +- API endpoints are accessible +- Request bodies match documented format +- Response bodies contain expected fields and values +- Status codes match documentation +- API calls can be chained (using data from one call in another) + +## Prerequisites + +- [Doc Detective installed](/docs/get-started/installation) +- Access to the API you're testing (production or staging) +- API credentials if required + +## Complete example + +```json title="api-tutorial.spec.json" +{ + "tests": [ + { + "steps": [ + { + "description": "Create a new user", + "httpRequest": { + "url": "https://reqres.in/api/users", + "method": "POST", + "request": { + "body": { + "name": "Test User", + "email": "test@example.com", + "job": "Documentation Tester" + } + }, + "response": { + "body": { + "name": "Test User", + "email": "test@example.com", + "job": "Documentation Tester", + "id": "string", + "createdAt": "string" + } + }, + "statusCodes": [201] + }, + "variables": { + "USER_ID": "$$response.body.id" + } + }, + { + "description": "Retrieve the created user by ID", + "httpRequest": { + "url": "https://reqres.in/api/users/$USER_ID", + "method": "GET", + "response": { + "body": { + "data": { + "id": "number" + } + } + }, + "statusCodes": [200] + } + }, + { + "description": "Update the user", + "httpRequest": { + "url": "https://reqres.in/api/users/$USER_ID", + "method": "PUT", + "request": { + "body": { + "name": "Updated User", + "job": "Senior Documentation Tester" + } + }, + "response": { + "body": { + "name": "Updated User", + "job": "Senior Documentation Tester", + "updatedAt": "string" + } + }, + "statusCodes": [200] + } + }, + { + "description": "Delete the user", + "httpRequest": { + "url": "https://reqres.in/api/users/$USER_ID", + "method": "DELETE", + "statusCodes": [204] + } + } + ] + } + ] +} +``` + +## Expected output + +When the test passes, you should see output showing all API calls succeeded: + +```json +{ + "summary": { + "steps": { + "pass": 4, + "fail": 0 + } + } +} +``` + +The user is created, retrieved, updated, and deleted successfully. The response bodies match the documented structure, and status codes are as expected. + +## Common variations + +**Test authentication with headers:** + +```json +{ + "description": "Call authenticated endpoint", + "httpRequest": { + "url": "https://api.example.com/protected", + "method": "GET", + "request": { + "headers": { + "Authorization": "Bearer $API_TOKEN" + } + }, + "statusCodes": [200] + } +} +``` + +**Validate specific response fields:** + +```json +{ + "description": "Check user has expected role", + "httpRequest": { + "url": "https://api.example.com/users/123", + "method": "GET", + "response": { + "body": { + "id": 123, + "role": "admin", + "email": "/.*@example\\.com$/" + } + }, + "statusCodes": [200] + } +} +``` + +**Test error responses:** + +```json +{ + "description": "Verify 404 for non-existent user", + "httpRequest": { + "url": "https://api.example.com/users/99999", + "method": "GET", + "response": { + "body": { + "error": "User not found" + } + }, + "statusCodes": [404] + } +} +``` + +## Next steps + +- Learn more about the [`httpRequest`](/docs/get-started/actions/httpRequest) action +- Explore [variables](/docs/get-started/actions/loadVariables) for chaining API calls +- Review [OpenAPI integration](/docs/references/schemas/httprequest) for automatic test generation diff --git a/docs/get-started/real-world-examples/ui-screenshots.mdx b/docs/get-started/real-world-examples/ui-screenshots.mdx new file mode 100644 index 00000000..54d4cb04 --- /dev/null +++ b/docs/get-started/real-world-examples/ui-screenshots.mdx @@ -0,0 +1,154 @@ +--- +sidebar_label: UI screenshots +description: Validate screenshots in UI walkthroughs with automated capture and visual comparison +--- + +# Validating screenshots in a UI walkthrough + +## When to use this + +Use this approach when your documentation includes UI walkthroughs with screenshots. Screenshots go stale when UIs change. Automated screenshot capture ensures visual documentation stays current. + +## What this tests + +- Pages load successfully +- Key UI elements are present +- Screenshots are captured at correct moments +- Visual changes are detected (if using comparison) + +## Prerequisites + +- [Doc Detective installed](/docs/get-started/installation) +- Access to the web application +- Browser installed (Firefox, Chrome, or Safari) + +## Complete example + +```json title="ui-screenshots.spec.json" +{ + "tests": [ + { + "steps": [ + { + "description": "Navigate to the application homepage", + "goTo": "https://example.com" + }, + { + "description": "Wait for page to fully load", + "find": { + "selector": "h1", + "timeout": 10000 + } + }, + { + "description": "Capture homepage screenshot", + "screenshot": { + "path": "screenshots/homepage.png" + } + }, + { + "description": "Click on the dashboard link", + "click": { + "selector": "a[href='/dashboard']" + } + }, + { + "description": "Wait for dashboard to load", + "find": { + "selector": ".dashboard-container", + "timeout": 10000 + } + }, + { + "description": "Capture dashboard screenshot with comparison", + "screenshot": { + "path": "screenshots/dashboard.png", + "maxVariation": 0.05, + "overwrite": "aboveVariation" + } + }, + { + "description": "Navigate to settings", + "goTo": "https://example.com/settings" + }, + { + "description": "Wait for settings page", + "find": { + "selector": "#settings-form", + "timeout": 10000 + } + }, + { + "description": "Capture settings screenshot", + "screenshot": { + "path": "screenshots/settings.png", + "maxVariation": 0.05, + "overwrite": "aboveVariation" + } + } + ] + } + ] +} +``` + +## Expected output + +When the test passes, you should see: + +```json +{ + "summary": { + "steps": { + "pass": 9, + "fail": 0 + } + } +} +``` + +Screenshot files are created in the `screenshots/` directory. If screenshots already exist and `maxVariation` is set, Doc Detective compares new screenshots with existing ones and only overwrites them if differences exceed the threshold. + +## Common variations + +**Capture full-page screenshots:** + +```json +{ + "description": "Capture full page including scrollable content", + "screenshot": { + "path": "screenshots/full-page.png", + "fullPage": true + } +} +``` + +**Screenshot specific elements:** + +```json +{ + "description": "Capture only the navigation bar", + "screenshot": { + "path": "screenshots/navbar.png", + "selector": ".navbar" + } +} +``` + +**Always overwrite screenshots:** + +```json +{ + "description": "Update screenshot every time", + "screenshot": { + "path": "screenshots/latest.png", + "overwrite": "always" + } +} +``` + +## Next steps + +- Learn more about the [`screenshot`](/docs/get-started/actions/screenshot) action +- Explore [visual comparison options](/docs/references/schemas/screenshot) for change detection +- Review the [capture screenshot tutorial](/docs/get-started/tutorials/capture-screenshot) for more details diff --git a/docs/get-started/real-world-examples/user-workflow.mdx b/docs/get-started/real-world-examples/user-workflow.mdx new file mode 100644 index 00000000..3284f8c5 --- /dev/null +++ b/docs/get-started/real-world-examples/user-workflow.mdx @@ -0,0 +1,181 @@ +--- +sidebar_label: User workflow +description: Test multi-step user workflows with end-to-end form filling and validation +--- + +# Testing a multi-step user workflow + +## When to use this + +Use this approach when you document complete workflows that span multiple pages or interactions, such as registration flows, checkout processes, or onboarding sequences. Testing these end-to-end ensures each step still works and properly leads to the next. + +## What this tests + +- Navigation between pages works +- Forms accept input correctly +- Buttons and links are clickable +- Success messages appear +- Workflow completes from start to finish + +## Prerequisites + +- [Doc Detective installed](/docs/get-started/installation) +- Access to the web application +- Test account credentials (if needed) + +## Complete example + +```json title="user-workflow.spec.json" +{ + "tests": [ + { + "steps": [ + { + "description": "Navigate to the registration page", + "goTo": "https://example.com/register" + }, + { + "description": "Wait for registration form to load", + "find": { + "selector": "#registration-form", + "timeout": 5000 + } + }, + { + "description": "Fill in username", + "find": { + "selector": "#username", + "click": true, + "type": "testuser_doc_detective" + } + }, + { + "description": "Fill in email address", + "find": { + "selector": "#email", + "click": true, + "type": "testuser@example.com" + } + }, + { + "description": "Fill in password", + "find": { + "selector": "#password", + "click": true, + "type": "SecurePassword123!" + } + }, + { + "description": "Fill in password confirmation", + "find": { + "selector": "#confirm-password", + "click": true, + "type": "SecurePassword123!" + } + }, + { + "description": "Accept terms of service", + "click": { + "selector": "#terms-checkbox" + } + }, + { + "description": "Submit the registration form", + "click": { + "selector": "button[type='submit']" + } + }, + { + "description": "Wait for success message", + "find": { + "selector": ".success-message", + "matchText": "Account created successfully", + "timeout": 10000 + } + }, + { + "description": "Capture confirmation page", + "screenshot": { + "path": "screenshots/registration-success.png" + } + }, + { + "description": "Verify redirect to dashboard", + "find": { + "selector": ".dashboard-welcome", + "matchText": "Welcome, testuser_doc_detective", + "timeout": 5000 + } + } + ] + } + ] +} +``` + +## Expected output + +When the test passes, you should see: + +```json +{ + "summary": { + "steps": { + "pass": 11, + "fail": 0 + } + } +} +``` + +The workflow executes from start to finish: the form is filled, submitted, success message appears, and the user is redirected to the dashboard. + +## Common variations + +**Test form validation:** + +```json +{ + "steps": [ + { + "description": "Submit form without filling required field", + "click": { + "selector": "button[type='submit']" + } + }, + { + "description": "Verify error message appears", + "find": { + "selector": ".error-message", + "matchText": "This field is required" + } + } + ] +} +``` + +**Wait for dynamic content to load:** + +```json +{ + "description": "Wait for loading spinner to disappear", + "wait": { + "duration": 2000 + } +} +``` + +**Use alternative selectors:** + +```json +{ + "description": "Click submit button using text", + "click": "Create Account" +} +``` + +## Next steps + +- Learn more about the [`find`](/docs/get-started/actions/find) action for interacting with forms +- Explore the [fill fields tutorial](/docs/get-started/tutorials/fill-fields) +- Review [selectors](/docs/category/selectors) for different ways to target elements diff --git a/sidebars.ts b/sidebars.ts index 7c81e679..6e759d0f 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -21,6 +21,23 @@ const sidebars: SidebarsConfig = { "get-started/installation/index", "get-started/concepts", "get-started/create-your-first-test", + { + type: "category", + label: "Real-world examples", + link: { + type: "doc", + id: "get-started/real-world-examples/overview", + }, + items: [ + "get-started/real-world-examples/overview", + "get-started/real-world-examples/cli-installation", + "get-started/real-world-examples/rest-api", + "get-started/real-world-examples/ui-screenshots", + "get-started/real-world-examples/user-workflow", + "get-started/real-world-examples/code-examples", + "get-started/real-world-examples/documentation-links", + ], + }, "get-started/sample-tests", "get-started/resources", ],