Spaces:
Running
Running
| # AutoSite Application Debug Guide | |
| ## Overview | |
| This document provides a comprehensive guide for debugging and testing the AutoSite application, with a particular focus on the AskAI component and its integration with the backend server. | |
| ## Application Structure | |
| ### Frontend Components | |
| - **App.tsx**: Main application container that manages the HTML content state and layout | |
| - **AskAI Component**: Handles AI interactions with streaming response processing | |
| - **Preview Component**: Renders HTML content in an iframe with refresh capability | |
| ### Backend Services | |
| - **/api/ask-ai**: Processes prompts and streams AI responses (full HTML or diff mode) | |
| - **/api/apply-diffs**: Applies diff blocks to original HTML content | |
| ## Key Features to Test | |
| ### AskAI Component | |
| 1. **Response Handling** | |
| - Full HTML mode for initial requests | |
| - Diff mode for follow-up requests | |
| - Streaming implementation with real-time preview updates | |
| 2. **Progress Indicators** | |
| - Progress bar with percentage | |
| - Response mode indicator (diff/full) | |
| - Loading animations | |
| - Success animation and sound | |
| 3. **Error Handling** | |
| - Network error handling | |
| - Authentication error handling with login modal | |
| - Malformed response handling | |
| ## Testing Resources | |
| The following files have been created to assist with testing: | |
| 1. **test-plan.md**: Comprehensive test plan outlining test cases and approaches | |
| 2. **test-html.html**: Sample HTML file for testing the application | |
| 3. **visual-test-script.js**: Browser-based script for testing UI components | |
| 4. **api-test-script.js**: Node.js script for testing backend API endpoints | |
| 5. **debug-report.md**: Detailed analysis of the application architecture and potential issues | |
| ## Running the Application | |
| ### Prerequisites | |
| 1. Create a `.env` file based on `.env.example` with the following variables: | |
| - `OAUTH_CLIENT_ID`: HuggingFace OAuth client ID | |
| - `OAUTH_CLIENT_SECRET`: HuggingFace OAuth client secret | |
| - `APP_PORT`: Port for the backend server (default: 3000) | |
| - `REDIRECT_URI`: OAuth redirect URI | |
| - `DEFAULT_HF_TOKEN`: HuggingFace API token for anonymous users | |
| ### Starting the Application | |
| 1. Start the frontend development server: | |
| ``` | |
| npm run dev | |
| ``` | |
| 2. Start the backend server in a separate terminal: | |
| ``` | |
| node server.js | |
| ``` | |
| 3. Access the application at: | |
| - Frontend: http://localhost:5173 | |
| - Backend API: http://localhost:3000 | |
| ## Testing Procedures | |
| ### Visual Testing | |
| 1. Open the application in a browser | |
| 2. Open the browser console | |
| 3. Load the visual test script: | |
| ```javascript | |
| const script = document.createElement('script'); | |
| script.src = '/visual-test-script.js'; | |
| document.head.appendChild(script); | |
| ``` | |
| 4. Run the tests: | |
| ```javascript | |
| runAllTests(); | |
| ``` | |
| ### API Testing | |
| 1. Ensure the backend server is running | |
| 2. Run the API test script using Node.js: | |
| ``` | |
| node api-test-script.js | |
| ``` | |
| ## Common Issues and Solutions | |
| ### Environment Configuration | |
| - **Missing HuggingFace Token**: The application requires a valid HuggingFace API token in the `DEFAULT_HF_TOKEN` environment variable | |
| - **Port Conflicts**: Ensure ports 3000 (backend) and 5173 (frontend) are available | |
| ### Network Issues | |
| - **CORS Errors**: If testing the frontend and backend on different ports, CORS issues may occur | |
| - **Rate Limiting**: HuggingFace API has rate limits that may affect testing | |
| ### UI Issues | |
| - **Responsive Layout**: Test on different screen sizes to verify responsive behavior | |
| - **Progress Indicator**: Verify progress updates correctly during streaming | |
| - **Preview Updates**: Check that preview updates in real-time during streaming | |
| ## Debugging Tips | |
| 1. **Console Logging**: The application includes extensive console logging for debugging | |
| 2. **Network Monitoring**: Use browser DevTools to monitor API requests and responses | |
| 3. **State Inspection**: Monitor React state changes during AI processing | |
| 4. **Visual Verification**: Check progress indicators and animations during processing | |
| ## Conclusion | |
| The AutoSite application demonstrates a well-structured approach to integrating AI assistance into a web development tool. The streaming response handling, progress indicators, and dual-mode response processing provide a solid foundation for an interactive AI-assisted development experience. | |
| Refer to the detailed test plan and debug report for more comprehensive information on testing and potential improvements. |