Skip to content

About

Free open-source exam simulator and quiz builder. Create exams visually or import JSON, organize courses, track scores and practice with filters. Works on GitHub Pages.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

🎓 ExamPreparation — Free Exam Simulator & Quiz Builder

A free, open-source exam simulator and quiz builder that runs directly in your browser—no account, backend, or installation required.

Build your own exams with a visual editor or import existing ones from JSON and ZIP files. Organize multiple courses, filter questions by topic or difficulty, track your scores locally, and review anything you missed.

Exam Simulator Live Demo

License: AGPL v3 i18n: PT / EN


🚀 Launch Simulator • 📖 User Guide • 📝 Question Formats • 🗺️ Codebase Map


📸 Screenshots

Subjects Catalog Exam List & Filters
Subjects Catalog Exam List and Filters
Interactive Exam Solver Dual-Pane Exam Builder
Interactive Exam Solver Dual-Pane Exam Builder

✨ Features

  • 🎯 Interactive Practice Modes:
    • Full exam simulations or targeted practice sessions.
    • Multi-faceted filters: filter by subject, specific exam, question count, difficulty ranges, and review missed or unanswered questions.
    • Performance analytics and score tracking with local storage persistence.
  • 📋 Multiple Question Formats:
    • Multiple Choice: Single or multi-select with dynamic option shuffling.
    • True or False (boolean): Clean binary format with fixed ordering.
    • Open / Written Response (escrita): Text input with guided self-assessment against the official solution.
    • Contextual headers (cabecalho field) for code snippets, markdown, or scenario descriptions across any question type.
    • For full JSON schema definitions and formatting rules, see QUESTION_FORMATS.md.
  • 🛠️ Exam Builder & Course Management:
    • Visual dual-pane editor to create, validate, and preview questions and exams in real time.
    • Import and export courses and exams as JSON or ZIP archives (persisted in browser storage).
  • 🌍 Internationalization (i18n):
    • Native bilingual support for Portuguese and English (PT/EN), switchable on the fly.
  • 🔒 Privacy & Performance:
    • 100% client-side execution; all web fonts (Inter, JetBrains Mono) are self-hosted with zero third-party tracking.

🗺️ Architecture & Codebase Map

The project is structured into focused ES modules, domain-specific modular stylesheets, and JSON-based exam data compiled via a standard library Python toolchain.

  • For an in-depth breakdown of modules, entry points, and directory layout, see codebase.md.
  • For step-by-step instructions on adding new courses, creating exam JSON files, and rebuild commands, see HOW_TO_USE.md.
  • Development rules, modularity standards, and contribution guidelines are detailed in AGENTS.md.

💻 Local Development & Testing

1. Local Tooling & Development Server

Core development tooling uses Python 3 standard library with zero external dependencies:

# Start local server at http://127.0.0.1:5000 and rebuild indexes
python run.py

# Recompile exam manifests and global catalog only (without starting the server)
python run.py --build-only

# Run strict schema and content validation on all exam files
python run.py --validate

2. Standard Unit & Integrity Tests

Run unit and integrity tests verifying schemas, import/export contracts, and DOM bindings:

python -m unittest discover -s tests -p "test_*.py"

🧪 Automated E2E Testing with Playwright

Automated end-to-end tests simulate real user flows (navigation, question solving, filters, and state transitions) in headless mode.

Note: External packages (such as Playwright and Pytest) must be installed inside a Python virtual environment (.venv) to keep the global system clean.

  1. Create and activate the virtual environment:

    python -m venv .venv
    .\.venv\Scripts\Activate.ps1
  2. Install testing dependencies and the Chromium browser:

    pip install -r requirements-dev.txt
    playwright install chromium
  3. Run the automated E2E test suite:

    pytest tests/e2e

    Or without manual activation:

    .\.venv\Scripts\pytest tests/e2e

About

Free open-source exam simulator and quiz builder. Create exams visually or import JSON, organize courses, track scores and practice with filters. Works on GitHub Pages.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages