ClipBin

Secure, shareable clipboard for teams and individuals.

---

Table of Contents

• Overview
• Key Features
• Tech Stack
• Getting Started
  • Prerequisites
  • Installation
  • Running the Development Server
• Configuration
• Usage Guide
• Contributing
• Community & Support
• License

---

Overview

ClipBin is a Flask-based web application for storing and sharing code snippets, configuration fragments, and other plaintext securely. It supports authenticated workflows for teams while also allowing anonymous users to create temporary clips with password protection.

---

Key Features

• Dark theme interface for comfortable reading.
• Anonymous and authenticated clip creation flows.
• Optional password protection with end-to-end encryption.
• Expiring links with configurable retention periods.
• Custom aliases for easy-to-remember URLs.
• File upload support for vetted text-based formats.
• User dashboard with clip management and exports.
• REST-style API endpoints for automation.

---

Tech Stack

Frontend

Backend

---

Getting Started

Prerequisites

• Python 3.10 or later
• pip 22+
• (Optional) Virtual environment tooling such as venv or pipenv

Installation

Clone the repository and install dependencies:

git clone https://github.com/alight659/ClipBin
cd ClipBin
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Running the Development Server

Start the Flask application:

python3 app.py

By default the server listens on http://127.0.0.1:5000. Enable debug mode locally by editing app.py and starting the app with app.run(debug=True).

---

Configuration

Variable	Description	Default
SECRET_KEY	Session encryption key used by Flask. Must be set in production.	None (Flask will raise if unset)
MAX_CONTENT_LENGTH	Maximum upload size for clips and files.	1.5 MB

Set environment variables in your shell before launching the app, for example:

export SECRET_KEY="change-me"

The application stores data in clipbin.db, an SQLite database created on first run. Back up this file for persistence.

---

Or use the Makefile for easier development:

# Start development server
make dev

# Install dependencies
make install

# Run tests quickly
make test-fast

# View all available commands
make help

To enable debugging mode, edit app.py

  app.run(debug=True)

Testing

This project includes a comprehensive test suite using pytest. The tests cover:

• Unit Tests: Individual function testing for utility modules
• Integration Tests: Complete workflow testing
• Database Tests: SQLite operations and data integrity
• Security Tests: XSS, SQL injection prevention
• API Tests: REST API endpoints

Quick Testing with Makefile

The easiest way to run tests is using the provided Makefile:

# View all available commands
make help

# Run all working tests (recommended)
make test-fast

# Run tests with coverage report
make test-coverage

# Run specific test categories
make test-unit          # Unit tests only
make test-integration   # Integration tests only

# Quick commands
make q                  # Quick test (alias for test-fast)
make qc                 # Quick test with coverage

Manual Testing

Install test dependencies (already included in requirements.txt):

pip install -r requirements.txt

Run all tests:

python -m pytest

Run tests with coverage report:

python -m pytest --cov=. --cov-report=html

Run specific test categories:

# Run only unit tests
python -m pytest tests/test_additional.py tests/test_sqlite.py

# Run integration tests
python -m pytest tests/test_integration.py

# Run with verbose output
python -m pytest -v

Use the convenient test runner script:

# Run all tests with coverage
python run_tests.py

# Run fast tests without coverage
python run_tests.py --fast

# Generate HTML coverage report
python run_tests.py --html-report

# Run only unit tests
python run_tests.py --type unit

Test Coverage

The project maintains high test coverage standards:

• Target Coverage: 90% minimum, 100% preferred
• Current Coverage:
  • additional.py: 100%
  • sqlite.py: 100%
  • app.py: Comprehensive route and functionality testing

View detailed coverage reports:

# Generate HTML report
python -m pytest --cov=. --cov-report=html
open htmlcov/index.html  # View in browser

Writing Tests

Tests are organized in the tests/ directory:

• test_additional.py: Utility function tests
• test_sqlite.py: Database operation tests
• test_app.py: Flask application route tests
• test_integration.py: End-to-end workflow tests
• conftest.py: Test configuration and fixtures

---

Usage Guide

1. Visit the home page and create a clip by entering a title and body or uploading a supported file.
2. Optionally set a password, mark the clip as editable, choose an expiration window, or supply a custom URL alias.
3. Share the resulting link. A separate /raw endpoint is available for plaintext retrieval, and /download/<id> exposes the content as a file.
4. Create an account to unlock the dashboard, manage existing clips, and export content as JSON, CSV, or plain text.

---

Contributing

Contributions that improve documentation, add features, or streamline the user experience are welcome. To get started:

1. Review the Contributing Guidelines and Code of Conduct.
2. Fork the repository and create a feature branch referencing the related issue.
3. Write clear commit messages and include tests or documentation updates when they apply.
4. Open a pull request explaining the motivation and testing performed.

Need inspiration? Check the issue tracker for help wanted and good first issues.

We ❤️ contributions!

Community & Support

Questions, bug reports, or feature ideas are encouraged. Reach the maintainers at [email protected] or open a GitHub issue.

---

License

ClipBin is released under the MIT License.