MoodChick 🐥✨

MoodChick is a fun, AI-powered caption and quote generator that creates social media captions based on your mood.
Select your mood, click generate, and let AI craft the perfect line for your post!

Features

🎨 Generate captions/quotes based on your mood (happy, sad, love, motivational, funny, etc.)
🤖 AI-powered text generation using HuggingFace flan-t5-small (free, lightweight)
📋 Copy-to-clipboard functionality
🔄 "Generate Again" button for endless inspiration
⚡ Easily extendable with more moods or AI models
📱 Responsive design for desktop and mobile
🚀 Automated CI pipeline for code quality
🔒 Pre-push git hooks to ensure quality before pushing
🧪 Comprehensive test suite with 85%+ coverage
📊 Automated coverage reporting

Getting Started

Prerequisites

Bun >= 1.0 (recommended) or Node.js >= 18
HuggingFace API key (optional, required for AI integration)

Installation

Clone the repository:

git clone https://github.com/YOUR_USERNAME/mood-chick.git
cd mood-chick

Install dependencies:
```
bun install
```

Set up environment variables (create .env.local):

NEXT_PUBLIC_HUGGINGFACE_API_KEY=your_api_key_here

Run the development server:
```
bun dev
```
Open http://localhost:3000 in your browser
(Optional) Run tests to ensure everything is working:
```
bun test
```

Available Scripts

bun dev - Start development server with Turbopack
bun build - Build for production
bun start - Start production server
bun lint - Run ESLint
bun type-check - Run TypeScript type checking
bun test - Run all tests
bun test:watch - Run tests in watch mode
bun test:coverage - Run tests with coverage report
bun test:ci - Run tests in CI mode with coverage

Testing

MoodChick has a comprehensive test suite to ensure code quality and prevent regressions.

Test Coverage

✅ Unit Tests - Testing individual functions and utilities
✅ API Route Tests - Testing all API endpoints (90%+ coverage)
✅ Component Tests - Testing React components (85%+ coverage)
✅ Integration Tests - Testing complete user workflows

Running Tests

Run All Tests

bun test

Run Tests in Watch Mode

Perfect for development - tests re-run automatically when files change:

bun test:watch

Run Tests with Coverage Report

bun test:coverage

This generates a coverage report in the coverage/ directory. Open coverage/lcov-report/index.html in your browser to see detailed coverage information.

Run Tests in CI Mode

bun test:ci

Test Structure

Tests are located alongside the code they test:

src/
├── app/
│   ├── __tests__/
│   │   └── page.test.tsx          # Home page component tests
│   ├── api/
│   │   └── generate-caption/
│   │       ├── __tests__/
│   │       │   └── route.test.ts  # API route tests
│   │       └── route.ts
│   └── page.tsx
└── lib/
    ├── __tests__/
    │   └── config.test.ts          # Config tests
    └── config.ts

What's Tested

API Routes (90%+ coverage)

✅ Caption generation for all moods (happy, sad, love, motivational, funny)
✅ Error handling for invalid requests
✅ Response format validation
✅ Edge cases (missing parameters, invalid JSON, etc.)
✅ Randomness in caption selection

Components (85%+ coverage)

✅ Rendering of all UI elements
✅ Mood selection and state management
✅ Caption generation flow
✅ Copy to clipboard functionality
✅ Loading states and error handling
✅ User interactions and events
✅ Complete user workflows

Configuration & Utilities

✅ Config object structure
✅ Environment variable handling
✅ Mood prompts validation

Writing Tests

When adding new features, follow these guidelines:

1. Test File Naming

Component tests: ComponentName.test.tsx
Unit tests: fileName.test.ts
Place tests in __tests__/ directories

2. Test Structure

import { render, screen } from "@testing-library/react";
import MyComponent from "../MyComponent";

describe("MyComponent", () => {
    it("should render correctly", () => {
        render(<MyComponent />);
        expect(screen.getByText("Hello")).toBeInTheDocument();
    });
});

3. Coverage Requirements

API routes: 90%+ coverage
Components: 85%+ coverage
Utilities: 90%+ coverage

Mocking

Mocking API Calls

global.fetch = jest.fn();
(global.fetch as jest.Mock).mockResolvedValueOnce({
    ok: true,
    json: async () => ({ caption: "Test caption" }),
});

Mocking Clipboard API

The clipboard API is automatically mocked in jest.setup.ts.

Coverage Thresholds

The project enforces minimum coverage thresholds:

{
  global: {
    branches: 80,
    functions: 85,
    lines: 85,
    statements: 85,
  },
  './src/app/api/**/*.ts': {
    branches: 90,
    functions: 90,
    lines: 90,
    statements: 90,
  },
}

Tests will fail if coverage drops below these thresholds.

Continuous Integration

Tests run automatically:

✅ On every push to main or develop
✅ On every pull request
✅ Before every push (via git hook)

See the CI/CD Pipeline section for more details.

CI/CD Pipeline

MoodChick uses GitHub Actions to automate code quality checks and ensure stability. The CI pipeline runs automatically on every push and pull request.

Workflows

1. CI Workflow (`.github/workflows/ci.yml`)

Runs on:

Push to main or develop branches
Pull requests to main or develop branches

Jobs:

Lint and Build

Tests on Node.js 18.x and 20.x
Runs ESLint for code quality
Performs TypeScript type checking
Builds the project to ensure compilation succeeds
Caches dependencies and Next.js build for faster runs
Uploads build artifacts (Node 20.x only)

Code Quality Checks

Checks for console statements (warning only)
Scans for TODO comments
Ensures code meets quality standards

Status Check

Final job that ensures all previous jobs passed
Blocks merging if any check fails

2. Test Workflow (`.github/workflows/test.yml`)

Runs on:

Push to main or develop branches
Pull requests to main or develop branches

Jobs:

Test

Runs complete test suite
Executes type checking and linting
Generates coverage reports
Uploads coverage to Codecov
Comments PR with coverage details
Enforces coverage thresholds

Integration

Runs integration tests
Verifies build succeeds
Ensures all components work together

CI Features

✅ Multi-Node Testing - Tests on Node.js 18.x and 20.x
✅ Smart Caching - Caches pnpm store and Next.js build for faster runs
✅ Build Artifacts - Saves build output for inspection
✅ Code Quality - Automated linting and type checking
✅ Parallel Jobs - Runs lint/build and code quality checks simultaneously

CI Status Badges

Add these badges to show CI status:

![CI](https://github.com/YOUR_USERNAME/mood-chick/actions/workflows/ci.yml/badge.svg)

Replace YOUR_USERNAME with your GitHub username.

Git Hooks

MoodChick uses Husky to enforce code quality before commits and pushes. This ensures that only validated code reaches the repository.

Pre-commit Hook

Runs automatically when you commit:

✅ ESLint checks

git commit -m "your message"
# 🐥 Running pre-commit checks...
# 🔍 Linting...
# ✅ Linting passed!

Pre-push Hook

Runs automatically before pushing to remote:

✅ Complete test suite with coverage
✅ Coverage threshold enforcement

git push
# 🧪 Running tests before push...
# PASS  src/app/__tests__/page.test.tsx
# PASS  src/app/api/generate-caption/__tests__/route.test.ts
# PASS  src/lib/__tests__/config.test.ts
# ✅ All tests passed!

Bypassing Hooks (Not Recommended)

If you need to bypass hooks in an emergency (not recommended):

# Skip pre-commit
git commit --no-verify -m "emergency fix"

# Skip pre-push
git push --no-verify

⚠️ Warning: Bypassing hooks can introduce bugs. Use only in emergencies.

Setting Up Hooks for Contributors

Hooks are automatically installed when running pnpm install thanks to the prepare script in package.json. If hooks aren't working:

# Manually reinstall Husky
pnpm run prepare

Development Workflow

Making Changes

Create a new branch:

git checkout -b feature/your-feature-name

Make your changes and commit:

git add .
git commit -m "Add your feature"
# Pre-commit hook runs linting

Push your changes:

git push origin feature/your-feature-name
# Pre-push hook runs all tests

Create a Pull Request:
- Go to GitHub and create a PR
- CI will automatically run all checks
- Wait for all checks to pass before merging

Pull Request Checks

When you open a PR, the following checks run automatically:

✅ Linting (ESLint)
✅ Type checking (TypeScript)
✅ Build verification
✅ Code quality scans
✅ Multi-version Node.js testing
✅ Complete test suite
✅ Coverage threshold validation
✅ Coverage report generation

All checks must pass before the PR can be merged.

Contributing

We welcome contributions! Please follow these guidelines:

Fork the repository
Clone your fork
Install dependencies: bun install
Create a branch: git checkout -b feature/amazing-feature
Make your changes

Run checks locally:

bun lint
bun type-check
bun test
bun build

Write tests for your changes (if applicable)
Commit your changes: Git hooks will run automatically
Push to your fork: git push origin feature/amazing-feature
Open a Pull Request

Code Quality Standards

Write clean, readable code
Follow TypeScript best practices
Use meaningful variable and function names
Comment complex logic
Write tests for new features and bug fixes
Maintain or improve code coverage
Ensure all CI checks pass
Test your changes locally before pushing

Commit Message Guidelines

Use clear, descriptive commit messages:

# Good
git commit -m "Add mood selector component"
git commit -m "Fix caption generation API error"
git commit -m "Update README with installation steps"

# Bad
git commit -m "update"
git commit -m "fix"
git commit -m "changes"

Tech Stack

Framework: Next.js 15
Language: TypeScript
Styling: Tailwind CSS 4
Icons: Lucide React
AI Model: HuggingFace flan-t5-small
Testing: Jest + React Testing Library
CI/CD: GitHub Actions
Git Hooks: Husky
Package Manager: Bun

Project Structure

mood-chick/
├── .github/
│   └── workflows/
│       ├── ci.yml          # CI pipeline configuration
│       └── test.yml        # Test workflow
├── .husky/                 # Git hooks
│   ├── pre-commit         # Linting before commit
│   └── pre-push           # Tests before push
├── __mocks__/             # Jest mocks
│   ├── fileMock.js
│   └── styleMock.js
├── public/                # Static assets
├── src/
│   ├── app/              # Next.js app directory
│   │   ├── __tests__/    # Component tests
│   │   ├── api/          # API routes
│   │   │   └── generate-caption/
│   │   │       ├── __tests__/  # API route tests
│   │   │       └── route.ts
│   │   ├── layout.tsx    # Root layout
│   │   ├── page.tsx      # Home page
│   │   └── globals.css   # Global styles
│   └── lib/              # Utility functions
│       ├── __tests__/    # Unit tests
│       └── config.ts
├── coverage/             # Test coverage reports (generated)
├── jest.config.ts        # Jest configuration
├── jest.setup.ts         # Jest setup file
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── eslint.config.mjs     # ESLint configuration
└── README.md             # This file

Troubleshooting

Git Hooks Not Running

# Reinstall Husky
bun run prepare

# Check hook permissions
chmod +x .husky/pre-commit
chmod +x .husky/pre-push

CI Checks Failing

# Run checks locally to debug
bun lint
bun type-check
bun test
bun build

Tests Failing

# Run tests in watch mode to debug
bun test:watch

# Run specific test file
bun test path/to/test.test.ts

# Run with coverage to see what's missing
bun test:coverage

Build Errors

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules
bun install

# Rebuild
bun build

License

This project is open source and available under the MIT License.

Acknowledgments

Built with ❤️ using Next.js and React
AI powered by HuggingFace
Icons by Lucide

Made with 🐥 by the MoodChick team

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github		.github
.husky		.husky
__mocks__		__mocks__
docs		docs
public		public
scripts		scripts
src		src
.gitignore		.gitignore
README.md		README.md
SETUP.md		SETUP.md
TESTING_SUMMARY.md		TESTING_SUMMARY.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
bun.lock		bun.lock
eslint.config.mjs		eslint.config.mjs
jest.config.ts		jest.config.ts
jest.setup.ts		jest.setup.ts
labels.yml		labels.yml
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation