Aris is a web-native scientific publishing platform that replaces static PDFs with interactive, accessible HTML documents. Built for researchers, academics, scientists, and students, Aris makes it easy to write, revise, collaborate, and publish work that’s readable on any device, bringing scientific publications to the web. See more at .
- Frontend: Node.js
>=23, NPM>=10 - Backend: Python
>=3.13, PostgreSQL>=14, FastAPI>=0.115
-
Clone the repository
git clone https://github.com/leotrs/aris.git cd aris -
Install Just (task runner)
# macOS brew install just # Or download from: https://github.com/casey/just/releases
-
Initialize development environment
just init # Sets up all .env files and installs dependenciesCRITICAL: All environment variables are REQUIRED. The system will crash immediately if any are missing.
-
Start development containers
just dev # Starts all services in Docker containers
aris/
│
├── backend/
├──── main.py # FastAPI app
├──── aris # package that contains routes, CRUD operations, etc
├──── scripts # DB management scripts
├──── tests # backend tests
│
├── frontend/
├──── index.html # mounting point for the app
├──── src # Vue 3 frontend source
├────── App.vue # Vue App component
├────── router.js # Vue Router component
├────── main.js # script that mounts the app
├────── File.js # object to hold a RSM file in memory
├────── FileStore.js # manage File objects
├────── login # login view: auth via JWT
├────── home # home view: view all files
├────── main # main view: read and edit a file
├────── assets # static resources
├────── common # common components
├────── components # legacy dir
├────── composables # Vue composables
│
├── docs/ # Project documentation
│
├── docker/ # Dockerfiles
│
└── README.md
Aris features a robust dual-database testing infrastructure with automatic database selection and per-worker isolation for reliable parallel test execution.
Local Development
- Database: SQLite (fast iteration, no setup required)
- Command:
uv run pytest -n8 - Features: Automatic in-memory databases, instant test execution
CI Environment
- Database: PostgreSQL 15 (production-like testing)
- Isolation: Per-worker databases (
test_aris_gw0_abc123,test_aris_gw1_def456, etc.) - Workers: 8 parallel test workers for maximum speed
- Features: Automatic database creation, cleanup, and worker isolation
Local CI Simulation
- Database: PostgreSQL (matches CI exactly)
- Command:
./simulate-ci -- uv run pytest -n8 - Features: 100% CI fidelity for debugging CI-specific issues
Backend Tests
- Unit Tests:
uv run pytest -n8- Test individual functions and API endpoints - Integration Tests:
tests/integration/- RSM processing, database constraints - Coverage: Generated in
htmlcov/directory - Database Selection: Automatic (SQLite locally, PostgreSQL in CI)
Frontend Tests
- Unit Tests:
npm test- Component and utility testing with Vitest - E2E Tests:
npm run test:e2e- End-to-end browser testing with Playwright
E2E tests require both backend and frontend servers running with a complete test environment.
- PostgreSQL Database: Running locally with
arisdatabase created - Environment Variables:
- Local Development: Both frontend and backend
.envfiles should contain test user credentials - CI Environment: Requires GitHub repository secret
TEST_USER_PASSWORD - Test User:
[email protected](password stored securely in environment variables)
- Local Development: Both frontend and backend
# 1. Setup Backend
cd backend
uv sync --all-groups # Install dependencies
alembic upgrade head # Run database migrations
uv run python scripts/reset_test_user.py # Create stable test data
uvicorn main:app --reload # Start backend server (localhost:8000)
# 2. Setup Frontend (in new terminal)
cd frontend
npm install # Install dependencies
npm run dev # Start frontend server (localhost:5173)
# 3. Run E2E Tests (in new terminal)
cd frontend
npm run test:e2e # Run Playwright tests- Test User:
[email protected]with stable test files and tags - Reset Script: Use
scripts/reset_test_user.pyto reset test environment to known state - Credential Security: Test user password stored in environment variables (never in version control)
- Single Source of Truth: All E2E tests use centralized credentials from
frontend/src/tests/e2e/setup/test-data.js - Visual Regression: Test data designed for consistent visual regression testing
- Backend: FastAPI server on
http://localhost:8000 - Frontend: Vue.js dev server on
http://localhost:5173 - Database: Local PostgreSQL with test user and stable data
- Authentication: JWT-based auth with test user credentials
- CI Requirements: GitHub repository secret
TEST_USER_PASSWORDmust be configured
Worker Isolation
- Each test worker gets an isolated database to prevent conflicts
- Database names include worker ID and unique hash:
test_aris_gw2_a1b2c3d4 - Automatic cleanup after test completion
Performance Benefits
- Local: 8x speedup with SQLite (in-memory databases)
- CI: 8x speedup with PostgreSQL (isolated databases)
- Reliability: No flaky tests due to database conflicts
Environment Detection
# Automatic database selection based on environment
if ENV == "CI" or os.environ.get("CI"):
# Use PostgreSQL with per-worker databases
return f"postgresql+asyncpg://postgres:postgres@localhost:5432/test_aris_{worker_id}_{unique_id}"
else:
# Use SQLite for fast local development
return f"sqlite+aiosqlite:///./test_{worker_id}_{unique_id}.db"PostgreSQL Service Container
services:
postgres:
image: postgres:15
env:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: test_aris
POSTGRES_HOST_AUTH_METHOD: trustFor E2E tests to run in CI, the following repository secret must be configured:
TEST_USER_PASSWORD: The password for[email protected](secure test user credentials)
- Go to your repository → Settings → Secrets and variables → Actions
- Click "New repository secret"
- Add
TEST_USER_PASSWORDwith the test user password value
Backend Testing
- Tests: 352 tests with 8 parallel workers
- Database: PostgreSQL 15 with per-worker isolation
- Quality: Linting (ruff), type checking (mypy)
- Coverage: Generated in
htmlcov/directory
Frontend Testing
- Unit Tests: Component and utility testing with Vitest
- Linting: ESLint for code quality
- E2E Tests: 7 mutually exclusive job categories for comprehensive coverage
E2E Test Architecture
- Total Coverage: 122 tests across 7 specialized job categories
- Authentication Control: Uses public demo routes for auth-free testing
- Tag-Based Selection: Precise test categorization with
@tagpatterns - Mutually Exclusive: Each test runs exactly once, no overlap
- Parallel Execution: All 7 jobs run simultaneously for maximum speed
E2E Job Categories
- e2e-auth (27 tests):
@auth[^-]- Core authentication-required functionality - e2e-auth-flows (22 tests):
@auth-flows- Login, registration, redirects - e2e-demo-content (37 tests):
@demo-content- Content rendering, navigation - e2e-demo-ui (33 tests):
@demo-ui- Workspace, annotations, interactions - e2e-core (3 tests):
@core- Critical smoke tests
# Backend tests (automatic database selection)
cd backend && uv run pytest -n8 # SQLite locally, fast iteration
cd backend && ./simulate-ci -- uv run pytest -n8 # PostgreSQL locally, CI simulation
# Frontend unit tests only
cd frontend && npm test
# E2E tests only (requires both servers running)
cd frontend && npm run test:e2e
# E2E tests by category (with both servers running)
cd frontend && npm run test:e2e -- --grep "@auth[^-]" # Auth-required tests
cd frontend && npm run test:e2e -- --grep "@auth-flows" # Auth flow tests
cd frontend && npm run test:e2e -- --grep "@demo-content" # Demo content tests
cd frontend && npm run test:e2e -- --grep "@demo-ui" # Demo UI tests
cd frontend && npm run test:e2e -- --grep "@core" # Core smoke tests
# Run all tests
cd backend && uv run pytest -n8
cd frontend && npm test && npm run test:e2e
# Debug CI issues locally
cd backend && ./simulate-ci -- uv run pytest tests/integration/ -v
# Analyze CI failures for GitHub PRs (requires Claude Code)
/ci-report # Analyze CI for current branch's PR
/ci-report 123 # Analyze CI for specific PR numberWe welcome contributions! Please see our Contributing Guide for details on how to get started.
Please ensure all tests pass and code is linted before submitting PRs:
# Run all checks (lint + typecheck + tests)
just check-all
# Or run individual commands:
just lint-all # Check code quality
just test-all # Run all testsTesting Infrastructure Notes
- Backend: Local development uses SQLite for fast iteration; CI uses PostgreSQL with per-worker database isolation
- E2E: Uses tag-based test selection for precise categorization and mutually exclusive execution
- Authentication: E2E tests use public demo routes for authentication-free testing
- Performance: Backend tests run with 8 parallel workers; E2E tests run in 7 parallel job categories
- Debug: Use
./simulate-cito debug CI-specific issues locally with 100% fidelity; use/ci-report(Claude Code) to analyze GitHub PR CI failures
This project is licensed under the MIT License - see the LICENSE file for details.
Made with <3 by leotrs.
Aris, empowering researchers, one draft at a time.