jinda 0.7.7.4 → 1.0.0

data/test/LOCAL_DEVELOPMENT.md

@@ -0,0 +1,345 @@
+# Local Development Testing Guide
+
+This guide explains how to run tests locally during Jinda gem development, matching the CI workflow.
+
+## Quick Start
+
+```bash
+# Run all tests (recommended before push)
+bundle exec rake
+
+# Or step by step:
+bundle exec rake test:unit        # Fast (2 seconds)
+bundle exec rake test:installation # Slow (2-3 minutes)
+bundle exec rake test:integration  # Slow (2-3 minutes)
+```
+
+## Test Structure
+
+### 1. Unit Tests (Fast - No App Generation)
+**Location**: `test/*_test.rb` (excluding integration_test.rb)
+**Purpose**: Static analysis of templates, controllers, models
+**Runtime**: ~2 seconds
+
+```bash
+bundle exec rake test:unit
+```
+
+**Files tested**:
+- `test/jenkins_stage_test.rb` - Verify Jenkinsfile structure
+- `test/note_model_test.rb` - Verify Note model templates
+- `test/api_notes_controller_test.rb` - Verify API controller templates
+- `test/note_validation_integration_test.rb` - Verify validation logic
+
+### 2. Installation Tests (Slow - Generates Test App)
+**Location**: `test/installation_test.rb`
+**Purpose**: Tests full installation flow, generates app in `tmp/jinda_tests/`
+**Runtime**: ~2-3 minutes
+
+```bash
+bundle exec rake test:installation
+```
+
+### 3. Integration Tests (Slow - Uses Generated App)
+**Location**: `test/integration_test.rb`  
+**Purpose**: Tests login, HTTP endpoints in generated app
+**Runtime**: ~2-3 minutes
+
+```bash
+bundle exec rake test:integration
+```
+
+### 4. Generated App Tests (Manual - Uses test/dummy)
+**Location**: `test/dummy/` (when manually created)
+**Purpose**: Test the actual generated application with its own test suite
+
+```bash
+# This only works if test/dummy exists
+bundle exec rake test:generated_app
+```
+
+## Working with test/dummy
+
+The `test/dummy` directory is **NOT** committed to git. It's for local development testing.
+
+### Creating test/dummy
+
+```bash
+cd test
+rm -rf dummy  # Clean any old version
+
+# Create new Rails app
+rails new dummy -BOTJ
+
+cd dummy
+
+# Add Jinda gem (local path)
+echo "gem 'jinda', path: '../../'" >> Gemfile
+
+# Install
+bundle install
+rails g jinda:install
+bundle install
+rails g jinda:config
+bundle install
+
+# Configure MongoDB
+# Edit config/mongoid.yml to use your MongoDB port
+
+# Seed
+rails jinda:seed
+
+# Test
+rails s
+```
+
+### Running tests in test/dummy
+
+```bash
+cd test/dummy
+
+# If it has Minitest
+bundle exec rake test
+
+# If it has RSpec
+bundle exec rspec
+
+# Or use the Rake task from gem root
+cd ../..
+bundle exec rake test:generated_app
+```
+
+## Local Development Workflow
+
+### Typical Development Cycle
+
+```bash
+# 1. Make changes to gem code (e.g., templates, generators)
+
+# 2. Run fast unit tests
+bundle exec rake test:unit
+
+# 3. If unit tests pass, regenerate test/dummy
+cd test
+rm -rf dummy
+rails new dummy -BOTJ
+cd dummy
+echo "gem 'jinda', path: '../../'" >> Gemfile
+bundle install
+rails g jinda:install
+bundle install
+rails g jinda:config
+bundle install
+cd ../..
+
+# 4. Run tests in dummy app
+cd test/dummy
+rails s  # Manual testing
+bundle exec rake test  # Automated tests
+cd ../..
+
+# 5. If all looks good, run full test suite
+bundle exec rake test:all
+
+# 6. Push to GitHub (CI will run same tests)
+git push
+```
+
+### Quick Development Cycle (Without test/dummy)
+
+```bash
+# For quick iterations on templates:
+bundle exec rake test:unit  # Fast feedback
+
+# When ready for full validation:
+bundle exec rake test:installation
+bundle exec rake test:integration
+```
+
+## Rake Tasks Reference
+
+### Available Tasks
+
+```bash
+# View all test tasks
+bundle exec rake -T test
+
+# Common tasks:
+rake test                  # Run unit + installation tests (default)
+rake test:unit            # Run unit tests only (fast)
+rake test:installation    # Run installation tests
+rake test:integration     # Run integration tests
+rake test:generated_app   # Run tests in test/dummy (if exists)
+rake test:gem             # Run gem-level tests (unit + installation)
+rake test:all             # Run all tests (unit + installation + integration)
+rake test_all             # Alias for test:all
+```
+
+### CI-Equivalent Commands
+
+To match what CI runs:
+
+```bash
+# CI runs these in parallel:
+bundle exec rake rubocop      # Code style
+bundle exec rake test:unit    # Fast tests
+
+# Then sequentially:
+bundle exec rake test:installation
+bundle exec rake test:integration
+```
+
+## Environment Variables
+
+### MongoDB Configuration
+```bash
+# Use custom MongoDB port
+MONGODB_PORT=27888 bundle exec rake test:installation
+
+# Skip cleanup (for debugging)
+SKIP_CLEANUP=true bundle exec rake test:installation
+```
+
+### Test App Location
+```bash
+# Use custom test directory
+TEST_DIR=/tmp/my_tests bundle exec rake test:installation
+```
+
+### Keep Test Artifacts
+```bash
+# Keep generated app after tests
+SKIP_CLEANUP=true bundle exec rake test:installation
+
+# App will be at: tmp/jinda_tests/jinda_test_*
+```
+
+## Prerequisites
+
+### Required Software
+- Ruby 3.3.x
+- Rails 7.0+
+- MongoDB (Docker or local)
+- Bundler
+
+### Start MongoDB
+```bash
+# Using Docker (recommended)
+docker run -d --name jinda_test_mongo -p 27017:27017 mongo
+
+# Verify
+docker ps | grep mongo
+```
+
+### Install Dependencies
+```bash
+bundle install
+gem install minitest-reporters  # Better test output
+```
+
+## Troubleshooting
+
+### MongoDB Connection Failed
+```bash
+# Check if MongoDB is running
+docker ps | grep mongo
+
+# Start if needed
+docker run -d -p 27017:27017 mongo
+```
+
+### Port Already in Use
+```bash
+# Find process
+lsof -i :3000
+
+# Kill it
+kill -9 <PID>
+```
+
+### test/dummy Issues
+```bash
+# Clean and recreate
+cd test
+rm -rf dummy
+# Then follow "Creating test/dummy" steps above
+```
+
+### Bundle Install Failures
+```bash
+# Clean bundle cache
+bundle clean --force
+rm Gemfile.lock
+bundle install
+```
+
+### Test Artifacts Remain
+```bash
+# Clean up
+rm -rf tmp/jinda_tests
+rm -rf test/dummy
+```
+
+## Syncing test/dummy Changes Back to Templates
+
+When you make changes in `test/dummy` that should be in the gem templates:
+
+```bash
+# 1. Find the file in test/dummy
+# Example: test/dummy/app/models/note.rb
+
+# 2. Copy to template location
+cp test/dummy/app/models/note.rb \
+   lib/generators/jinda/templates/app/models/note.rb
+
+# 3. Verify with unit tests
+bundle exec rake test:unit
+
+# 4. Verify by regenerating dummy
+cd test
+rm -rf dummy
+# ... recreate dummy ...
+# ... verify it still works ...
+```
+
+**Future Enhancement**: We'll add a rake task to automate this sync.
+
+## CI vs Local Differences
+
+| Aspect | Local | CI |
+|--------|-------|-----|
+| test/dummy | Manually created, not in git | Not used |
+| Test apps | `tmp/jinda_tests/` or custom | `$WORKSPACE/tmp/jinda_tests/` |
+| MongoDB | Docker on localhost | Docker container in CI |
+| Cleanup | Optional (SKIP_CLEANUP) | Always cleanup |
+| Parallel tests | Sequential by default | Parallel stages |
+
+## Best Practices
+
+### Before Committing
+1. Run `bundle exec rake test:unit` (fast check)
+2. Run `bundle exec rake test:installation` (full check)
+3. Manually test in `test/dummy` if you changed generators
+
+### During Development
+1. Keep `test/dummy` up to date with your changes
+2. Run unit tests frequently (they're fast)
+3. Run installation tests before pushing
+
+### Before Release
+1. Run full test suite: `bundle exec rake test:all`
+2. Test in fresh `test/dummy`
+3. Verify CI passes
+
+## Related Documentation
+
+- `test/UNIT_TESTS_README.md` - Unit test details
+- `ci/Jenkinsfile.simple` - CI configuration
+- `Rakefile` - Test task definitions
+- `README.md` - Gem installation guide
+
+---
+
+**Last Updated**: 2026-01-04  
+**Ruby Version**: 3.3.x  
+**Rails Version**: 7.0+

data/test/README.md

@@ -0,0 +1,243 @@
+# Jinda Gem Test Suite
+
+This directory contains the Minitest-based test suite for the Jinda gem installation and functionality.
+
+## Overview
+
+The test suite validates the complete Jinda gem installation process, ensuring:
+- All installation steps work correctly
+- The Rails application starts successfully
+- The dashboard is accessible on localhost:3000
+- All required files are created
+
+## Test Files
+
+- `installation_test.rb` - Complete installation workflow test
+- `test_helper.rb` - Test configuration and reporters
+
+## Running Tests Locally
+
+### Prerequisites
+
+Ensure you have:
+- Ruby 3.3.0+ (as specified in `jinda.gemspec`)
+- Rails 7.1.0+ (as specified in `jinda.gemspec`)
+- MongoDB running (Docker or local)
+
+### Start MongoDB
+
+```bash
+# Using Docker
+docker run -d --name jinda_test_mongodb -p 27888:27017 mongo:latest
+
+# Or use existing container
+docker start jindaapp-mongodb-1
+```
+
+### Run All Tests
+
+```bash
+cd ~/mygem/jinda
+ruby test/installation_test.rb
+```
+
+Or using Rake:
+
+```bash
+rake test
+```
+
+### Run with Custom MongoDB Port
+
+```bash
+MONGODB_PORT=27017 ruby test/installation_test.rb
+```
+
+### Keep Test App for Debugging
+
+```bash
+SKIP_CLEANUP=true ruby test/installation_test.rb
+```
+
+The test app will be preserved at: `~/tmp/jinda_tests/jinda_test_<timestamp>`
+
+### Run Specific Test
+
+```bash
+ruby test/installation_test.rb --name test_05_jinda_install_generator
+```
+
+## Test Execution Order
+
+Tests run sequentially and build on each other:
+
+1. **test_01_prerequisites** - Checks Ruby, Rails, MongoDB
+2. **test_02_create_rails_app** - Creates new Rails app
+3. **test_03_add_jinda_to_gemfile** - Adds Jinda gem
+4. **test_04_bundle_install_initial** - Initial bundle install
+5. **test_05_jinda_install_generator** - Runs `rails g jinda:install`
+6. **test_06_bundle_install_post_generator** - Bundle after generator
+7. **test_07_jinda_config_generator** - Runs `rails g jinda:config`
+8. **test_08_update_mongodb_config** - Updates MongoDB port
+9. **test_09_jinda_seed** - Runs `rails jinda:seed`
+10. **test_10_rails_environment_loads** - Tests Rails initialization
+11. **test_11_rails_server_starts_and_responds** - Tests server & HTTP
+12. **test_12_verify_installation_files** - Verifies all files exist
+
+If any test fails, subsequent tests are skipped.
+
+## GitHub CI Integration
+
+The test suite runs automatically on GitHub Actions when you push to:
+- `main` branch
+- `develop` branch
+- Any `jinda-*` branch (e.g., `jinda-0.9.0`)
+
+### CI Configuration
+
+The CI workflow (`.github/workflows/ci.yml`):
+- Automatically reads Ruby and Rails versions from `jinda.gemspec`
+- Sets up MongoDB service
+- Runs all tests
+- Uploads test artifacts on failure
+
+### No Hardcoded Versions
+
+The CI dynamically reads versions from your gemspec:
+```yaml
+- name: Read Ruby version from gemspec
+  run: grep 'required_ruby_version' jinda.gemspec | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'
+
+- name: Read Rails version from gemspec
+  run: grep "add_runtime_dependency 'rails'" jinda.gemspec | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'
+```
+
+This means when you update versions in `jinda.gemspec`, CI automatically uses them.
+
+## Test Output
+
+### Successful Run
+```
+Run options: --seed 12345
+
+# Running:
+
+JindaInstallationTest
+  test_01_prerequisites                             PASS (0.15s)
+  test_02_create_rails_app                          PASS (12.34s)
+  test_03_add_jinda_to_gemfile                      PASS (0.02s)
+  test_04_bundle_install_initial                    PASS (25.67s)
+  test_05_jinda_install_generator                   PASS (8.90s)
+  test_06_bundle_install_post_generator             PASS (15.23s)
+  test_07_jinda_config_generator                    PASS (3.45s)
+  test_08_update_mongodb_config                     PASS (0.01s)
+  test_09_jinda_seed                                PASS (2.34s)
+  test_10_rails_environment_loads                   PASS (5.67s)
+  test_11_rails_server_starts_and_responds          PASS (12.89s)
+  test_12_verify_installation_files                 PASS (0.05s)
+
+Finished in 86.72s
+12 tests, 23 assertions, 0 failures, 0 errors, 0 skips
+```
+
+### With Skipped Tests (MongoDB not running)
+```
+JindaInstallationTest
+  test_01_prerequisites                             SKIP
+    MongoDB container not running - start with: docker run -d -p 27888:27017 mongo
+```
+
+## Troubleshooting
+
+### Test Hangs on Server Start
+If test_11 hangs:
+1. Check if port 3000 is already in use: `lsof -i :3000`
+2. Kill any processes on that port
+3. Run with `SKIP_CLEANUP=true` to debug
+
+### Bundle Install Fails
+Check that `~/mygem/jinda` path exists and contains valid gem code.
+
+### MongoDB Connection Errors
+1. Verify MongoDB is running: `docker ps | grep mongo`
+2. Check port is correct: `MONGODB_PORT=27888`
+3. Test connection: `mongosh --host localhost --port 27888`
+
+### Permission Errors
+Ensure `~/tmp/jinda_tests` is writable:
+```bash
+mkdir -p ~/tmp/jinda_tests
+chmod 755 ~/tmp/jinda_tests
+```
+
+## Development Workflow
+
+### After Making Changes
+
+Run tests after modifying:
+- `lib/generators/jinda/install_generator.rb`
+- `lib/generators/jinda/config_generator.rb`
+- `jinda.gemspec` dependencies
+- Dashboard views
+- Core gem functionality
+
+### Quick Test Cycle
+
+```bash
+# Make changes to gem
+vim lib/generators/jinda/install_generator.rb
+
+# Run tests
+ruby test/installation_test.rb
+
+# If test fails, preserve app for debugging
+SKIP_CLEANUP=true ruby test/installation_test.rb
+
+# Manually inspect test app
+cd ~/tmp/jinda_tests/jinda_test_XXXXX
+```
+
+### Before Pushing to GitHub
+
+```bash
+# Run full test suite
+rake test
+
+# If all pass, push to GitHub
+git push origin jinda-0.9.0
+```
+
+GitHub Actions will automatically run the same tests in CI.
+
+## Adding New Tests
+
+To add a new test:
+
+1. Add test method to `installation_test.rb`:
+```ruby
+def test_13_my_new_test
+  skip unless File.directory?(@test_app_path)
+  
+  # Your test logic here
+  assert something, "Error message"
+end
+```
+
+2. Follow naming convention: `test_##_descriptive_name`
+3. Use `skip unless File.directory?(@test_app_path)` to chain tests
+4. Run locally to verify
+5. Push to GitHub to run in CI
+
+## Environment Variables
+
+- `MONGODB_PORT` - MongoDB port (default: 27888)
+- `SKIP_CLEANUP` - Keep test app after run (default: false)
+
+## Future Enhancements
+
+- [ ] Test theme installation (adminlte, adminbsb)
+- [ ] Test Freemind integration
+- [ ] Test user authentication flows
+- [ ] Test API endpoints
+- [ ] Performance benchmarks
+- [ ] Multi-version testing (Ruby 3.3.x matrix)