attune/docs/testing/test-user-setup.md

Test User Setup Guide

This guide explains how to create and manage test users in Attune for development and testing.

Quick Setup

Create Default Test User

Run the script to create a test user with default credentials:

./scripts/create-test-user.sh

Default Credentials:

• Login: test@attune.local
• Password: TestPass123!
• Display Name: Test User

Test Login

Once created, test the login via API:

curl -X POST http://localhost:8080/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"login":"test@attune.local","password":"TestPass123!"}'

Successful Response:

{
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": 2,
      "login": "test@attune.local",
      "display_name": "Test User"
    }
  }
}

Custom User Credentials

Using Environment Variables

Create a user with custom credentials:

TEST_LOGIN="myuser@example.com" \
TEST_PASSWORD="MySecurePass123!" \
TEST_DISPLAY_NAME="My Custom User" \
./scripts/create-test-user.sh

Environment Variables

Variable	Description	Default
TEST_LOGIN	User login/email	test@attune.local
TEST_PASSWORD	User password	TestPass123!
TEST_DISPLAY_NAME	User display name	Test User
ATTUNE_DB_NAME	Database name	attune
ATTUNE_DB_HOST	Database host	localhost
ATTUNE_DB_PORT	Database port	5432
ATTUNE_DB_USER	Database user	postgres
ATTUNE_DB_PASSWORD	Database password	postgres

Password Hashing

Attune uses Argon2id for password hashing, which is a secure, modern password hashing algorithm.

Generate Password Hash Manually

To generate a password hash for manual database insertion:

cargo run --example hash_password "YourPasswordHere"

Example Output:

$argon2id$v=19$m=19456,t=2,p=1$F0UlGNd21LBXF7TWmpD93w$F65DKRjPU6japrzYv3ZcddnMFCtjVIBDWIkiLbkqt2I

Manual Database Insertion

Insert a user directly via SQL:

INSERT INTO identity (login, display_name, password_hash, attributes)
VALUES (
    'user@example.com',
    'User Name',
    '$argon2id$v=19$m=19456,t=2,p=1$...',  -- Hash from above
    '{}'::jsonb
);

Updating Existing Users

Update Password via Script

If the user already exists, the script will prompt to update:

./scripts/create-test-user.sh
# Outputs: "User 'test@attune.local' already exists"
# Prompts: "Do you want to update the password? (y/N):"

Auto-confirm update:

echo "y" | ./scripts/create-test-user.sh

Update Password via SQL

Directly update a user's password in the database:

-- Generate hash first: cargo run --example hash_password "NewPassword"

UPDATE identity
SET password_hash = '$argon2id$v=19$m=19456,t=2,p=1$...',
    updated = NOW()
WHERE login = 'test@attune.local';

Multiple Database Support

Create users in different databases/schemas:

Development Database (public schema)

ATTUNE_DB_NAME=attune \
./scripts/create-test-user.sh

E2E Test Database

ATTUNE_DB_NAME=attune_e2e \
./scripts/create-test-user.sh

Custom Database

ATTUNE_DB_NAME=my_custom_db \
ATTUNE_DB_HOST=db.example.com \
ATTUNE_DB_PASSWORD=secretpass \
./scripts/create-test-user.sh

Verification

Check User Exists

Query the database to verify user creation:

psql postgresql://postgres:postgres@localhost:5432/attune \
  -c "SELECT id, login, display_name FROM identity WHERE login = 'test@attune.local';"

Expected Output:

 id |       login       | display_name
----+-------------------+--------------
  2 | test@attune.local | Test User

Test Authentication

Use curl to test login:

# Login
TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"login":"test@attune.local","password":"TestPass123!"}' \
  | jq -r '.data.access_token')

# Use token for authenticated request
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/packs

Security Considerations

Development vs Production

⚠️ Important Security Notes:

1. Never use test credentials in production

   • Default test user (test@attune.local) is for development only
   • Change or remove before production deployment

2. Password Strength

   • Default password (TestPass123!) is intentionally simple for testing
   • Production passwords should be stronger and unique

3. Database Access

   • Test user creation requires direct database access
   • In production, create users via API with proper authentication

4. Password Storage

   • Never store passwords in plain text
   • Always use the Argon2id hashing mechanism
   • Never commit password hashes to version control

Production User Creation

In production, users should be created through:

1. API Registration Endpoint (if enabled)
2. Admin Interface (web UI)
3. CLI Tool with proper authentication
4. Database Migration for initial admin user only

Troubleshooting

Script Fails to Connect

Error: Cannot connect to database attune

Solutions:

• Verify PostgreSQL is running: pg_isready -h localhost -p 5432
• Check database exists: psql -l | grep attune
• Verify credentials are correct
• Create database: ./scripts/setup-db.sh

Password Hash Generation Fails

Error: Failed to generate password hash

Solutions:

• Ensure Rust toolchain is installed: cargo --version
• Build the project first: cargo build
• Use pre-generated hash for default password (already in script)

Login Fails After User Creation

Possible Causes:

1. Wrong Database Schema

   • Verify API service uses same schema as user creation
   • Check config: grep schema config.development.yaml

2. Password Mismatch

   • Ensure password hash matches the password
   • Regenerate hash: cargo run --example hash_password "YourPassword"

3. User Not Found

   • Verify user exists in database
   • Check correct database is being queried

API Returns 401 Unauthorized

Check:

• User exists in database
• Password hash is correct
• API service is running and connected to correct database
• JWT secret is configured properly

Related Documentation

• Configuration Guide - Database and security settings
• API Authentication - JWT tokens and authentication flow
• Running Tests - E2E testing with test users
• Database Setup - Initial database configuration

Script Location

The test user creation script is located at:

scripts/create-test-user.sh

Source Code:

• Password hashing: crates/api/src/auth/password.rs
• Hash example: crates/common/examples/hash_password.rs
• Identity model: crates/common/src/models.rs

Examples

Create Admin User

TEST_LOGIN="admin@company.com" \
TEST_PASSWORD="SuperSecure123!" \
TEST_DISPLAY_NAME="System Administrator" \
./scripts/create-test-user.sh

Create Multiple Test Users

# User 1
TEST_LOGIN="alice@test.com" \
TEST_DISPLAY_NAME="Alice Test" \
./scripts/create-test-user.sh

# User 2
TEST_LOGIN="bob@test.com" \
TEST_DISPLAY_NAME="Bob Test" \
./scripts/create-test-user.sh

# User 3
TEST_LOGIN="charlie@test.com" \
TEST_DISPLAY_NAME="Charlie Test" \
./scripts/create-test-user.sh

Create E2E Test User

ATTUNE_DB_NAME=attune_e2e \
TEST_LOGIN="e2e@test.local" \
TEST_PASSWORD="E2ETest123!" \
./scripts/create-test-user.sh

Summary

• ✅ Simple: One command to create test users
• ✅ Flexible: Customizable via environment variables
• ✅ Secure: Uses Argon2id password hashing
• ✅ Safe: Prompts before overwriting existing users
• ✅ Verified: Includes login test instructions

For production deployments, use the API or admin interface to create users with proper authentication and authorization checks.