capydash 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d65145bed2681cec5831f3f5b8715c90f06fe94d7f88d3fa7c8cb85781ef8f7
+  data.tar.gz: 8fa286bd777abe9c901d34587bcefb5b25f6dad9d73bda2a7ee8b28419552634
+SHA512:
+  metadata.gz: 0e329477548327159151a4a88a54bd12fd53444a6c3c7ca56381f88ca2042d08e6a6b0e7f365f38a15d97c3f61a347884a43a7c31d4791c7775cce7e6b9c09e7
+  data.tar.gz: f3fd9b929e4a0bbe145078fe48769280ab40b965099a0e2eb4a581e508963c2c84117009775544eaf9511c231eaf4a9ded96b6893faff543a93e336e311d8413

data/README.md

@@ -0,0 +1,286 @@
+# CapyDash
+
+A real-time test monitoring dashboard for Rails applications that provides live visualization of test execution with screenshots, step-by-step tracking, and comprehensive error reporting.
+
+## Features
+
+- **Real-time Test Monitoring**: Watch tests execute live with WebSocket updates
+- **Visual Test Flow**: See each test step with screenshots and detailed information
+- **Hierarchical Organization**: Test classes → methods → individual steps
+- **Screenshot Capture**: Automatic screenshots at each test step
+- **Error Tracking**: Comprehensive error reporting and logging
+- **Configurable**: YAML-based configuration system
+- **Production Ready**: Built-in logging, error handling, and persistence
+
+## Quick Start
+
+### 1. Installation
+
+#### Option A: Install from RubyGems (Recommended)
+
+Add to your Gemfile:
+
+```ruby
+gem 'capydash'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+#### Option B: Install from source
+
+```bash
+git clone https://github.com/damonclark/capydash.git
+cd capydash
+bundle install
+```
+
+#### Option C: Local development
+
+For local development, add to your Gemfile:
+
+```ruby
+gem 'capydash', path: '/path/to/capydash'
+```
+
+### 2. Configuration
+
+Create a configuration file at `config/capydash.yml`:
+
+```yaml
+# CapyDash Configuration
+server:
+  host: "localhost"
+  port: 4000
+  max_connections: 100
+
+dashboard:
+  title: "My Test Dashboard"
+  auto_scroll: true
+  show_timestamps: true
+
+tests:
+  system_tests_dir: "test/system"
+  feature_tests_dir: "test/features"
+  screenshot_dir: "tmp/capydash_screenshots"
+
+logging:
+  level: "info"
+  file: "log/capydash.log"
+
+security:
+  enable_auth: false
+  secret_key: "your-secret-key-here"
+```
+
+### 3. Setup in Rails
+
+Add to your `test/test_helper.rb`:
+
+```ruby
+require 'capydash'
+
+# CapyDash will automatically instrument your tests
+```
+
+### 4. Running Tests
+
+#### Option A: Standalone Server (Recommended)
+
+```bash
+# Terminal 1: Start the dashboard server
+bundle exec rake capydash:server
+
+# Terminal 2: Run tests with external WebSocket
+CAPYDASH_EXTERNAL_WS=1 bundle exec rails test
+```
+
+#### Option B: In-Process Server (Development)
+
+```bash
+# Just run your tests - CapyDash starts automatically
+bundle exec rails test
+```
+
+### 5. View Dashboard
+
+Open your browser to `http://localhost:4000` to see the live test dashboard.
+
+## Configuration Options
+
+### Server Configuration
+
+```yaml
+server:
+  host: "localhost"              # Server host
+  port: 4000                     # Server port
+  websocket_path: "/websocket"   # WebSocket endpoint
+  max_connections: 100           # Max concurrent connections
+  message_history_limit: 1000    # Max messages to keep in memory
+```
+
+### Dashboard Configuration
+
+```yaml
+dashboard:
+  title: "CapyDash Test Monitor"  # Dashboard title
+  refresh_interval: 1000          # UI refresh rate (ms)
+  auto_scroll: true               # Auto-scroll to latest step
+  show_timestamps: true           # Show timestamps in UI
+  screenshot_quality: 0.8         # Screenshot compression (0.0-1.0)
+  max_screenshot_width: 1200      # Max screenshot width (px)
+```
+
+### Test Configuration
+
+```yaml
+tests:
+  default_directory: "test"                    # Default test directory
+  system_tests_dir: "test/system"             # System tests directory
+  feature_tests_dir: "test/features"          # Feature tests directory
+  controller_tests_dir: "test/controllers"    # Controller tests directory
+  model_tests_dir: "test/models"              # Model tests directory
+  screenshot_dir: "tmp/capydash_screenshots"  # Screenshot storage
+  timeout: 300                                # Test timeout (seconds)
+```
+
+### Logging Configuration
+
+```yaml
+logging:
+  level: "info"           # Log level: debug, info, warn, error
+  file: "log/capydash.log" # Log file path
+  max_file_size: "10MB"   # Max log file size
+  max_files: 5            # Number of log files to keep
+```
+
+### Security Configuration
+
+```yaml
+security:
+  enable_auth: false                    # Enable authentication
+  secret_key: "your-secret-key-here"   # Secret key for tokens
+  session_timeout: 3600                # Session timeout (seconds)
+```
+
+## Usage
+
+### Running Individual Test Classes
+
+The dashboard allows you to run individual test classes by clicking the "Run" button next to each class. CapyDash automatically:
+
+1. Detects the test class name from the test method names
+2. Generates the appropriate file path (e.g., `NavigationTest` → `test/system/navigation_test.rb`)
+3. Executes the test with proper environment setup
+
+### Running All Tests
+
+Click "Run All System Tests" to execute all system tests with live monitoring.
+
+### Viewing Test Results
+
+- **Test Classes**: Top-level organization by test class
+- **Test Methods**: Individual test methods within each class
+- **Test Steps**: Detailed step-by-step execution with screenshots
+- **Status Indicators**: Visual status for each level (PASSED/FAILED/RUNNING)
+- **Error Details**: Comprehensive error information for failed tests
+
+## Development
+
+### Project Structure
+
+```
+lib/capydash/
+├── engine.rb              # Rails engine integration
+├── instrumentation.rb     # Capybara method instrumentation
+├── dashboard_server.rb    # WebSocket server
+├── event_emitter.rb       # Event broadcasting
+├── forwarder.rb          # External WebSocket forwarding
+├── configuration.rb      # Configuration management
+├── logger.rb             # Logging system
+├── error_handler.rb      # Error handling
+├── persistence.rb        # Data persistence
+└── auth.rb              # Authentication
+
+dashboard/
+├── src/
+│   └── App.jsx          # React dashboard
+└── public/              # Static assets
+
+config/
+└── capydash.yml         # Configuration file
+```
+
+### Adding New Features
+
+1. **Configuration**: Add new options to `Configuration` class
+2. **Logging**: Use `CapyDash::Logger` for all logging
+3. **Error Handling**: Use `CapyDash::ErrorHandler` for error management
+4. **Persistence**: Use `CapyDash::Persistence` for data storage
+
+### Testing
+
+```bash
+# Run the dummy app tests
+cd spec/dummy_app
+bundle exec rails test
+
+# Run with CapyDash monitoring
+CAPYDASH_EXTERNAL_WS=1 bundle exec rails test
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **WebSocket Connection Failed**
+   - Check if port 4000 is available
+   - Verify firewall settings
+   - Check server logs for errors
+
+2. **Tests Not Appearing**
+   - Ensure `CAPYDASH_EXTERNAL_WS=1` is set
+   - Check that tests are in the correct directories
+   - Verify test class naming conventions
+
+3. **Screenshots Not Capturing**
+   - Check screenshot directory permissions
+   - Verify Capybara configuration
+   - Check available disk space
+
+### Debug Mode
+
+Enable debug logging:
+
+```yaml
+logging:
+  level: "debug"
+```
+
+### Logs
+
+Check logs at:
+- `log/capydash.log` - Application logs
+- `tmp/capydash_screenshots/` - Screenshot storage
+- `tmp/capydash_data/` - Test run persistence
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Support
+
+- GitHub Issues: [Report bugs and request features](https://github.com/damonclark/capydash/issues)
+- Documentation: [Full documentation](https://github.com/damonclark/capydash/wiki)
+- Examples: [Example configurations and usage](https://github.com/damonclark/capydash/examples)

data/capydash.gemspec

@@ -0,0 +1,30 @@
+# capydash.gemspec
+require_relative "lib/capydash/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "capydash"
+  spec.version       = Capydash::VERSION
+  spec.authors       = ["Damon Clark"]
+  spec.email         = ["dclark312@gmail.com"]
+
+  spec.summary       = "Real-time Capybara test dashboard"
+  spec.description   = "CapyDash instruments Capybara tests and streams test steps, screenshots, and DOM snapshots to a live dashboard."
+  spec.homepage      = "https://github.com/damonclark/capydash"
+  spec.license       = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files         = Dir["lib/**/*", "bin/*", "README.md", "LICENSE*", "*.gemspec"]
+  spec.require_paths = ["lib"]
+
+  # Dependencies
+  spec.add_runtime_dependency "capybara", ">= 3.0"
+  spec.add_runtime_dependency "faye-websocket"
+  spec.add_runtime_dependency "eventmachine"
+  spec.add_runtime_dependency "em-websocket"
+
+  # Development dependencies
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rails", "~> 7.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+end

data/lib/capydash/auth.rb

@@ -0,0 +1,103 @@
+require 'securerandom'
+require 'digest'
+
+module CapyDash
+  class Auth
+    class << self
+      def authenticate(username, password)
+        return false unless auth_enabled?
+
+        # Simple hardcoded credentials for MVP
+        # In production, this would connect to a proper user database
+        valid_credentials = {
+          'admin' => 'capydash123',
+          'developer' => 'test123',
+          'viewer' => 'readonly123'
+        }
+
+        if valid_credentials[username] == password
+          token = generate_token(username)
+          Logger.info("User authenticated", {
+            username: username,
+            token: token[0..8] + "..."
+          })
+          token
+        else
+          Logger.warn("Authentication failed", {
+            username: username,
+            ip: current_ip
+          })
+          nil
+        end
+      end
+
+      def validate_token(token)
+        return false unless auth_enabled?
+        return false unless token && token.length > 10
+
+        # Simple token validation for MVP
+        # In production, this would use JWT or similar
+        begin
+          decoded = Base64.decode64(token)
+          parts = decoded.split(':')
+          return false unless parts.length == 3
+
+          username, timestamp, signature = parts
+          expected_signature = generate_signature(username, timestamp)
+
+          if signature == expected_signature
+            # Check if token is not expired (24 hours)
+            token_time = Time.at(timestamp.to_i)
+            if Time.now - token_time < 24 * 60 * 60
+              Logger.debug("Token validated", { username: username })
+              username
+            else
+              Logger.warn("Token expired", { username: username })
+              false
+            end
+          else
+            Logger.warn("Invalid token signature", { token: token[0..8] + "..." })
+            false
+          end
+        rescue => e
+          ErrorHandler.handle_error(e, {
+            error_type: 'authentication',
+            operation: 'validate_token'
+          })
+          false
+        end
+      end
+
+      def auth_enabled?
+        CapyDash.config.auth_enabled?
+      end
+
+      def require_auth!
+        return true unless auth_enabled?
+        # This would be called by middleware or controllers
+        # For now, just return true
+        true
+      end
+
+      private
+
+      def generate_token(username)
+        timestamp = Time.now.to_i.to_s
+        signature = generate_signature(username, timestamp)
+        token_data = "#{username}:#{timestamp}:#{signature}"
+        Base64.encode64(token_data).strip
+      end
+
+      def generate_signature(username, timestamp)
+        secret = CapyDash.config.secret_key
+        data = "#{username}:#{timestamp}:#{secret}"
+        Digest::SHA256.hexdigest(data)
+      end
+
+      def current_ip
+        # In a real app, this would get the actual IP
+        "127.0.0.1"
+      end
+    end
+  end
+end

data/lib/capydash/configuration.rb

@@ -0,0 +1,186 @@
+module CapyDash
+  class Configuration
+    attr_accessor :server, :dashboard, :tests, :logging, :security, :performance
+
+    def initialize
+      @server = {
+        host: "localhost",
+        port: 4000,
+        websocket_path: "/websocket",
+        max_connections: 100,
+        message_history_limit: 1000
+      }
+
+      @dashboard = {
+        title: "CapyDash Test Monitor",
+        refresh_interval: 1000,
+        auto_scroll: true,
+        show_timestamps: true,
+        screenshot_quality: 0.8,
+        max_screenshot_width: 1200
+      }
+
+      @tests = {
+        default_directory: "test",
+        system_tests_dir: "test/system",
+        feature_tests_dir: "test/features",
+        controller_tests_dir: "test/controllers",
+        model_tests_dir: "test/models",
+        screenshot_dir: "tmp/capydash_screenshots",
+        timeout: 300
+      }
+
+      @logging = {
+        level: "info",
+        file: "log/capydash.log",
+        max_file_size: "10MB",
+        max_files: 5
+      }
+
+      @security = {
+        enable_auth: false,
+        secret_key: "your-secret-key-here",
+        session_timeout: 3600
+      }
+
+      @performance = {
+        enable_compression: true,
+        cleanup_interval: 300,
+        max_memory_usage: "512MB"
+      }
+    end
+
+    def self.load_from_file(config_path = nil)
+      config_path ||= File.join(Dir.pwd, "config", "capydash.yml")
+
+      if File.exist?(config_path)
+        require 'yaml'
+        yaml_config = YAML.load_file(config_path)
+
+        config = new
+        config.load_from_hash(yaml_config)
+        config
+      else
+        # Return default configuration if file doesn't exist
+        new
+      end
+    rescue => e
+      puts "Warning: Could not load configuration from #{config_path}: #{e.message}"
+      puts "Using default configuration."
+      new
+    end
+
+    def load_from_hash(hash)
+      @server.merge!(hash['server']) if hash['server']
+      @dashboard.merge!(hash['dashboard']) if hash['dashboard']
+      @tests.merge!(hash['tests']) if hash['tests']
+      @logging.merge!(hash['logging']) if hash['logging']
+      @security.merge!(hash['security']) if hash['security']
+      @performance.merge!(hash['performance']) if hash['performance']
+    end
+
+    def server_host
+      @server[:host]
+    end
+
+    def server_port
+      @server[:port]
+    end
+
+    def websocket_path
+      @server[:websocket_path]
+    end
+
+    def max_connections
+      @server[:max_connections]
+    end
+
+    def message_history_limit
+      @server[:message_history_limit]
+    end
+
+    def dashboard_title
+      @dashboard[:title]
+    end
+
+    def auto_scroll?
+      @dashboard[:auto_scroll]
+    end
+
+    def show_timestamps?
+      @dashboard[:show_timestamps]
+    end
+
+    def screenshot_quality
+      @dashboard[:screenshot_quality]
+    end
+
+    def max_screenshot_width
+      @dashboard[:max_screenshot_width]
+    end
+
+    def system_tests_dir
+      @tests[:system_tests_dir]
+    end
+
+    def feature_tests_dir
+      @tests[:feature_tests_dir]
+    end
+
+    def controller_tests_dir
+      @tests[:controller_tests_dir]
+    end
+
+    def model_tests_dir
+      @tests[:model_tests_dir]
+    end
+
+    def screenshot_dir
+      @tests[:screenshot_dir]
+    end
+
+    def test_timeout
+      @tests[:timeout]
+    end
+
+    def log_level
+      @logging[:level]
+    end
+
+    def log_file
+      @logging[:file]
+    end
+
+    def max_files
+      @logging[:max_files]
+    end
+
+    def max_file_size
+      @logging[:max_file_size]
+    end
+
+    def auth_enabled?
+      @security[:enable_auth]
+    end
+
+    def secret_key
+      @security[:secret_key]
+    end
+
+    def session_timeout
+      @security[:session_timeout]
+    end
+
+    def compression_enabled?
+      @performance[:enable_compression]
+    end
+
+    def cleanup_interval
+      @performance[:cleanup_interval]
+    end
+
+    def max_memory_usage
+      @performance[:max_memory_usage]
+    end
+  end
+end