Fixtures

Fixtures are JSON files that contain sample data for your application. They help you set up initial data, test data, and seed your database with predefined records.

What are Fixtures?

Fixtures are structured JSON files that define sample data for your doctypes. They are automatically applied when you run commands like nailgun migrate or nailgun push, ensuring your database has the necessary initial data.

File Structure

Fixtures are stored in the fixtures/ directory within each app:

apps/your-app/
├── fixtures/
│   ├── doctype_name.fixture.json
│   └── another_doctype.fixture.json

Fixture File Format

Fixture files follow the naming convention: {doctype_name}.fixture.json

For example:

• zodula__User.fixture.json - for the User doctype
• zodula__Role.fixture.json - for the Role doctype

JSON Structure

Each fixture file contains an array of objects representing the records to be inserted:

[
  {
    "id": "record-1",
    "name": "Sample Record 1",
    "description": "This is a sample record",
    "is_active": true
  },
  {
    "id": "record-2", 
    "name": "Sample Record 2",
    "description": "Another sample record",
    "is_active": false
  }
]

Example: Role Fixtures

Here's a complete example of a Role fixture file:

[
  {
    "id": "Anonymous",
    "name": "Anonymous",
    "description": "The person who is not logged in"
  },
  {
    "id": "Authenticated", 
    "name": "Authenticated",
    "description": "The person who is logged in"
  },
  {
    "id": "System Admin",
    "name": "System Admin", 
    "description": "The person who has all the permissions"
  },
  {
    "id": "Test",
    "name": "Test",
    "description": null
  }
]

When Fixtures are Applied

Fixtures are automatically applied during:

1. Database Migration - When running nailgun migrate
2. Push Operations - When running nailgun push
3. Fresh Setup - When setting up a new environment
4. Development - When starting development with sample data

Creating Fixtures

Method 1: Manual Creation

Create a new .fixture.json file in your app's fixtures/ directory:

# Navigate to your app
cd apps/your-app

# Create fixtures directory if it doesn't exist
mkdir -p fixtures

# Create a fixture file
touch fixtures/YourDoctype.fixture.json

Method 2: Export from Database

You can export existing data as fixtures using the API:

POST /api/action/zodula.fixtures.exports
Content-Type: application/json

{
  "app": "your-app",
  "doctype": "YourDoctype", 
  "ids": ["record-1", "record-2"],
  "fields": ["name", "description"]
}

Best Practices

1. Use Meaningful IDs

Use descriptive, stable IDs that won't change:

[
  {
    "id": "admin-role",
    "name": "Administrator"
  },
  {
    "id": "user-role", 
    "name": "User"
  }
]

2. Include Required Fields

Make sure to include all required fields for your doctype:

[
  {
    "id": "user-001",
    "name": "John Doe",
    "email": "john@example.com",
    "is_active": true
  }
]

3. Use Consistent Data

Keep fixture data consistent and realistic:

[
  {
    "id": "product-001",
    "name": "Laptop Computer",
    "price": 999.99,
    "category": "Electronics",
    "in_stock": true
  }
]

4. Handle Relationships

When fixtures reference other records, use the same IDs:

[
  {
    "id": "order-001",
    "customer": "customer-001", 
    "product": "product-001",
    "quantity": 2
  }
]

Common Use Cases

1. System Roles

Define default user roles and permissions:

[
  {
    "id": "admin",
    "name": "Administrator",
    "permissions": ["read", "write", "delete"]
  },
  {
    "id": "user",
    "name": "User", 
    "permissions": ["read"]
  }
]

2. Configuration Data

Set up application configuration:

[
  {
    "id": "app-config",
    "app_name": "My Application",
    "version": "1.0.0",
    "maintenance_mode": false
  }
]

3. Test Data

Create sample data for development:

[
  {
    "id": "customer-001",
    "name": "Acme Corporation",
    "email": "contact@acme.com",
    "status": "active"
  },
  {
    "id": "customer-002", 
    "name": "Tech Solutions Inc",
    "email": "info@techsolutions.com",
    "status": "active"
  }
]

Troubleshooting

Fixtures Not Applied

If fixtures aren't being applied:

1. Check file naming: {doctype_name}.fixture.json
2. Verify JSON syntax is valid
3. Ensure doctype exists and is properly defined
4. Run nailgun migrate or nailgun push

Duplicate Records

If you get duplicate record errors:

1. Check for existing records with the same IDs
2. Use unique IDs in your fixtures
3. Consider using upsert operations for updates

Invalid Data

If fixtures fail to load:

1. Validate JSON syntax
2. Check that all required fields are present
3. Ensure field types match doctype definitions
4. Verify foreign key references exist

Tips

• Keep fixtures small and focused
• Use fixtures for essential system data
• Test fixtures in development before production
• Document the purpose of each fixture file
• Consider using different fixtures for different environments
• Use version control to track fixture changes

Related Commands

• nailgun migrate - Apply migrations and fixtures
• nailgun push - Push changes and apply fixtures
• nailgun sync - Sync schema without fixtures
• nailgun scaffold - Create new apps with fixture directories