Insites Unit Tests

Expected: Version number displayed. If command not found, install insites-cli first.

2. Verify Environment Configuration

cd project_directory && insites-cli env list

Expected: At least one staging/development environment listed.

3. Verify Module Installation

insites-cli modules list <env>

Expected: test module appears in the list.

4. Install Required Module - SKIP if user module already installed

insites-cli modules install tests
insites-cli modules download test
insites-cli deploy staging

Phase 1: Test Planning

1.1 Announce Your Test Plan

YOU MUST announce your test plan BEFORE writing any code. State explicitly:

• What functionality you are testing
• Which assertions you will use
• What edge cases you will cover
• Expected success and failure scenarios

ANNOUNCE: "I am planning tests for [FEATURE]. I will test:
1. [SUCCESS SCENARIO] using [ASSERTION]
2. [FAILURE SCENARIO] using [ASSERTION]
3. [EDGE CASE] using [ASSERTION]"

1.2 Identify Test Location

Every test file MUST be placed in: app/lib/tests/ direcory

Every test file MUST end with: _test.liquid

VALID:   app/lib/test/user_test.liquid
VALID:   app/lib/test/auth/login_test.liquid
INVALID: app/lib/tests/user.liquid
INVALID: app/tests/user_test.liquid
INVALID: tests/user_test.liquid

1.3 Map Assertions to Requirements

Before writing, map each requirement to an assertion:

1.4 Components That MUST Have Unit Tests

YOU MUST identify testable components before writing any code. The following components require unit tests in order of priority:

1.4.1 Commands (HIGHEST PRIORITY)

Commands contain business logic. These are your PRIMARY test targets.

app/lib/commands/
├── users/
│   ├── create.liquid      → test/commands/users/create_test.liquid
│   ├── update.liquid      → test/commands/users/update_test.liquid
│   └── delete.liquid      → test/commands/users/delete_test.liquid
├── orders/
│   ├── place.liquid       → test/commands/orders/place_test.liquid
│   └── cancel.liquid      → test/commands/orders/cancel_test.liquid

What to test in commands:

• Valid input produces expected output
• Invalid input returns validation errors
• Edge cases (empty values, max lengths, special characters)
• Business rules are enforced
• Side effects occur correctly (records created, emails sent)

1.4.2 Validators (HIGH PRIORITY)

Custom validation logic that commands depend on.

app/lib/validators/
├── email_format.liquid    → test/validators/email_format_test.liquid
├── phone_number.liquid    → test/validators/phone_number_test.liquid
├── unique_slug.liquid     → test/validators/unique_slug_test.liquid

What to test in validators:

• Valid inputs pass validation (return no errors)
• Invalid inputs fail with correct error messages
• Boundary conditions (min/max length, format edges)

1.4.3 Queries (MEDIUM-HIGH PRIORITY)

GraphQL queries wrapped in Liquid functions.

app/lib/queries/
├── users/
│   ├── find.liquid        → test/queries/users/find_test.liquid
│   ├── search.liquid      → test/queries/users/search_test.liquid
│   └── list.liquid        → test/queries/users/list_test.liquid

What to test in queries:

• Query returns expected data structure
• Query handles missing records gracefully (returns nil or empty)
• Filters work correctly
• Pagination returns correct subsets
• Sorting produces expected order

1.4.4 Authorization/Permissions (HIGH PRIORITY)

Access control logic that gates functionality.

app/lib/authorization/
├── can_edit.liquid        → test/authorization/can_edit_test.liquid
├── can_delete.liquid      → test/authorization/can_delete_test.liquid
├── can_view.liquid        → test/authorization/can_view_test.liquid

What to test in authorization:

• Authorized users CAN perform action (returns true)
• Unauthorized users CANNOT perform action (returns false)
• Edge cases: no user, suspended user, expired session
• Role-based access: admin vs regular user vs guest

1.4.5 Helpers/Utilities (MEDIUM PRIORITY)

Reusable utility functions used across the application.

app/lib/helpers/
├── format_currency.liquid → test/helpers/format_currency_test.liquid
├── slugify.liquid         → test/helpers/slugify_test.liquid
├── truncate_text.liquid   → test/helpers/truncate_text_test.liquid

What to test in helpers:

• Correct output for typical inputs
• Edge cases: nil, empty string, special characters
• Boundary values (very long strings, zero, negative numbers)

1.4.6 Background Jobs (MEDIUM PRIORITY)

Async processes triggered by events or schedules.

app/lib/jobs/
├── send_digest.liquid     → test/jobs/send_digest_test.liquid
├── cleanup_expired.liquid → test/jobs/cleanup_expired_test.liquid

What to test in jobs:

• Job executes successfully with valid data
• Job handles missing or invalid data gracefully
• Job produces expected side effects

1.5 Test Planning Matrix

Use this matrix when planning tests for ANY component:

1.6 Test Planning Template

Before writing tests for any component, YOU MUST complete this template:

COMPONENT: [path/to/component.liquid]
PURPOSE: [What this component does]

SUCCESS SCENARIOS:
1. [Describe valid input scenario] → [assertion to use]
2. [Describe another success case] → [assertion to use]

FAILURE SCENARIOS:
3. [Describe invalid input] → [assertion: not_valid_object or presence on errors]
4. [Describe authorization failure] → [assertion to use]
5. [Describe not found case] → [assertion to use]

EDGE CASES:
6. [Describe edge case 1] → [assertion to use]
7. [Describe edge case 2] → [assertion to use]

TEST FILE: app/lib/test/[path]_test.liquid

1.7 Example: Complete Test Plan for User Registration

COMPONENT: app/lib/commands/users/create.liquid PURPOSE: Creates a new user account with email and password

SUCCESS SCENARIOS:
1. Valid email and password creates user → valid_object
2. Created user has correct email stored → equal
3. Created user has generated ID → presence
4. Created user has hashed password (not plaintext) → not_equal
5. Welcome email is triggered → valid_object on email result

FAILURE SCENARIOS:
6. Missing email returns validation error → not_valid_object
7. Invalid email format rejected → not_valid_object
8. Password too short rejected → not_valid_object
9. Password missing rejected → not_valid_object
10. Duplicate email rejected → not_valid_object
11. Error message mentions 'email' for email errors → presence on errors.email

EDGE CASES:
12. Email with leading/trailing whitespace is trimmed → equal (trimmed value)
13. Email is lowercased for storage → equal (lowercase value)
14. Very long valid email (254 chars) works → valid_object
15. Email at max+1 length rejected → not_valid_object
16. Unicode in password accepted → valid_object
17. SQL injection attempt in email safely rejected → not_valid_object

TEST FILE: app/lib/test/commands/users/create_test.liquid

1.8 What NOT to Test

DO NOT write unit tests for these components:

1.9 Test Prioritization Order

When adding tests to an existing codebase or starting fresh, prioritize in this order:

1. Commands that handle money/transactions - Bugs here cause financial loss
2. Commands that create/modify user data - Bugs here cause data corruption
3. Authorization/permission logic - Bugs here cause security vulnerabilities
4. Validators used by multiple commands - High impact, many dependents
5. Commands that send external communications - Emails, SMS, webhooks
6. Complex queries with business logic - Filtering, aggregation, calculations
7. Helpers used across the application - High reuse means high impact
8. Background jobs - Failures may go unnoticed without tests

RULE: Start with components where bugs cause the most damage.

1.10 Test Coverage Requirements

Minimum coverage requirements by component type:

Phase 2: Writing Tests

2.1 Example Test File

{% comment %}
  Test: Invalid email - should be invalid
{% endcomment %}
{% liquid
  assign data = '{ "email": "invalid-email", "body": "This is a valid message body." }' | parse_json
  function contact = 'commands/contacts/create', object: data

  function contract = 'modules/tests/assertions/not_valid_object', contract: contract, object: contact, field_name: 'contact'
  function contract = 'modules/tests/assertions/presence', contract: contract, object: contact.errors, field_name: 'email'
%}

2.1.1 How to Structure Multi-Test Files

{% comment %}
  Test: Valid input - should be considered valid
{% endcomment %}

{% liquid
  assign data = '{ "email": "[email protected]", "body": "This is a valid message body." }' | parse_json
  function contact = 'commands/contacts/create', object: data

  # 1. Contact should be valid
  function contract = 'modules/tests/assertions/valid_object', contract: contract, object: contact, field_name: 'contact'

  # 2. Email should be downcased
  assign expected_email = '[email protected]'
  assign given_email = contact.email
  function contract = 'modules/tests/assertions/equal', contract: contract, expected: expected_email, given: given_email, field_name: 'contact.email'

  # 3. Body should match
  assign expected_body = 'This is a valid message body.'
  assign given_body = contact.body
  function contract = 'modules/tests/assertions/equal', contract: contract, expected: expected_body, given: given_body, field_name: 'contact.body'

  # 4: Assert the contact.valid is true
  function contract = 'modules/tests/assertions/true', contract: contract, object: contact, field_name: 'valid'

  # 5: Errors should be blank
  function contract = 'modules/tests/assertions/blank', contract: contract, object: contact, field_name: 'errors'
%}

2.2 Contract Initialization

The contract object is MANDATORY. Every test MUST:

1. Initialize the contract at the start
2. Pass the contract to every assertion
3. Return the contract at the end

{% liquid
  # CORRECT - Initialize first
  function contract = 'modules/tests/helpers/init'

  # ... test code ...

  # CORRECT - Return last
  return contract
%}

FAILURE MODE: Omitting contract initialization causes silent test failures. The test appears to pass but validates nothing.

2.3 Using Assertions

2.3.1 Equal Assertion

Use when: Comparing two values for exact equivalence

{% liquid
  function contract = 'modules/tests/helpers/init'

  assign expected = "hello"
  assign actual = "hello"

  function contract = 'modules/tests/assertions/equal',
    contract: contract,
    expected: expected,
    actual: actual,
    field_name: 'greeting_value'

  return contract
%}

2.3.2 Blank Assertion

Use when: Field must be absent, null, or empty string

{% liquid
  function contract = 'modules/tests/helpers/init'

  assign user = null | hash
  assign user['email'] = null

  function contract = 'modules/tests/assertions/blank',
    contract: contract,
    object: user,
    field_name: 'email'

  return contract
%}

2.3.3 Presence Assertion

Use when: Field MUST exist and have a non-null value

{% liquid
  function contract = 'modules/tests/helpers/init'

  assign user = null | hash
  assign user['id'] = 123

  function contract = 'modules/tests/assertions/presence',
    contract: contract,
    object: user,
    field_name: 'id'

  return contract
%}

2.3.4 Not Presence Assertion

Use when: Field must be null or absent

{% liquid
  function contract = 'modules/tests/helpers/init'

  assign response = null | hash
  assign response['error'] = null

  function contract = 'modules/tests/assertions/not_presence',
    contract: contract,
    object: response,
    field_name: 'error'

  return contract
%}

2.3.5 Valid Object Assertion

Use when: Testing that object.valid returns true

{% liquid
  function contract = 'modules/tests/helpers/init'

  # Create/fetch an object that has validation
  function user = 'lib/commands/users/create', email: '[email protected]'

  function contract = 'modules/tests/assertions/valid_object',
    contract: contract,
    object: user,
    field_name: 'user_creation'

  return contract
%}

2.3.6 Not Valid Object / Invalid Object Assertions

Use when: Testing that validation FAILS as expected

{% liquid
  function contract = 'modules/tests/helpers/init'

  # Create object with invalid data
  function user = 'lib/commands/users/create', email: 'invalid-email'

  function contract = 'modules/tests/assertions/not_valid_object',
    contract: contract,
    object: user,
    field_name: 'invalid_user_rejected'

  return contract
%}

2.3.7 Object Contains Object Assertion

Use when: Validating specific key-value pairs exist in object

{% liquid
  function contract = 'modules/tests/helpers/init'

  assign response = null | hash
  assign response['status'] = 'success'
  assign response['code'] = 200

  assign expected_subset = null | hash
  assign expected_subset['status'] = 'success'

  function contract = 'modules/tests/assertions/object_contains_object',
    contract: contract,
    object: response,
    subset: expected_subset,
    field_name: 'response_status'

  return contract
%}

2.3.8 True / Not True Assertions

Use when: Evaluating boolean conditions

{% liquid
  function contract = 'modules/tests/helpers/init'

  assign is_admin = true

  function contract = 'modules/tests/assertions/true',
    contract: contract,
    value: is_admin,
    field_name: 'admin_flag'

  assign is_deleted = false

  function contract = 'modules/tests/assertions/not_true',
    contract: contract,
    value: is_deleted,
    field_name: 'not_deleted'

  return contract
%}

2.4 Custom Assertions

Use when: Built-in assertions are insufficient

{% liquid
  function contract = 'modules/tests/helpers/init'

  # Custom validation logic
  assign value = "test string"
  assign length = value | size

  if length < 5
    function contract = 'modules/tests/helpers/register_error',
      contract: contract,
      field_name: 'string_length',
      message: 'String must be at least 5 characters'
  endif

  return contract
%}

2.5 Multiple Assertions Per Test

Every test MUST have at least one assertion. Multiple assertions are permitted and encouraged for comprehensive coverage:

{% liquid
  function contract = 'modules/tests/helpers/init'

  function user = 'lib/commands/users/create',
    email: '[email protected]',
    name: 'Test User'

  # Assertion 1: Creation succeeded
  function contract = 'modules/tests/assertions/valid_object',
    contract: contract,
    object: user,
    field_name: 'user_valid'

  # Assertion 2: Email is set
  function contract = 'modules/tests/assertions/presence',
    contract: contract,
    object: user,
    field_name: 'email'

  # Assertion 3: ID was generated
  function contract = 'modules/tests/assertions/presence',
    contract: contract,
    object: user,
    field_name: 'id'

  return contract
%}

Phase 3: Running Tests

3.1 Deployment Before Testing

YOU MUST deploy before running tests. Every time. No exceptions.

# MANDATORY before any test run
insites-cli deploy staging

3.2 Running Tests via CLI

Primary method for CI/CD and local development:

# Run ALL tests
insites-cli test run staging

# Run specific test file
insites-cli test run staging test/user_test

# Run tests in subdirectory
insites-cli test run staging test/auth/login_test

Exit codes:

• 0 = All tests passed
• Non-zero = Test failures occurred

3.3 Running via curl

# Run all tests and get JSON response
curl https://your-instance.staging.oregon.platform-os.com/_tests/run.js

# Run a specific test
curl "https://your-instance.staging.oregon.platform-os.com/_tests/run.js?name=test/examples/assertions_test"

# List all available tests as JSON
curl https://your-instance.staging.oregon.platform-os.com/_tests.js

3.4 Running Tests via Browser

For debugging and manual inspection:

3.5 Async Test Execution

For long-running test suites:

GET /_tests/run_async

This initiates background execution. Monitor via logs:

insites-cli logsv2 staging

3.6 Real-Time Development

For active development, use sync mode:

# Terminal 1: Start sync
insites-cli sync staging

# Terminal 2: Watch logs
insites-cli logsv2 staging

# Terminal 3: Run tests as needed
insites-cli test run staging test/your_test

Phase 4: Email Testing

4.1 Accessing Sent Emails

Navigate to: /_tests/sent_mails

This endpoint displays paginated email records from test execution.

4.2 Inspecting Individual Emails

Navigate to: /_tests/sent_mails/:id

Replace :id with the email record ID to view full email details including:

• Recipients
• Subject
• Body content
• Headers
• Attachments

4.3 Email Assertions in Tests

{% liquid
  function contract = 'modules/tests/helpers/init'

  # Trigger email sending
  function result = 'lib/commands/notifications/send_welcome_email',
    user_id: user.id

  # Verify email was sent successfully
  function contract = 'modules/tests/assertions/valid_object',
    contract: contract,
    object: result,
    field_name: 'welcome_email_sent'

  return contract
%}

Phase 5: Fixing Failing Tests

5.1 Diagnostic Protocol

When a test fails, YOU MUST execute this protocol IN ORDER:

1. Read the error message completely
2. Identify the failing assertion by field_name
3. Check the actual vs expected values
4. Trace back to the source of incorrect data
5. Fix the root cause, not the symptom

5.2 Common Failures and Fixes

Contract Not Initialized

Symptom: Test runs but no assertions execute

Fix:

{% liquid
  # ADD THIS AS FIRST LINE
  function contract = 'modules/tests/helpers/init'

  # ... rest of test ...

  return contract
%}

Contract Not Returned

Symptom: Test appears to pass but results aren't collected

Fix:

{% liquid
  function contract = 'modules/tests/helpers/init'

  # ... test code ...

  # ADD THIS AS LAST LINE
  return contract
%}

Wrong File Location

Symptom: Test not discovered by runner

Fix: Move file to app/lib/test/ with _test.liquid suffix

Assertion Receives Nil Contract

Symptom: Error about nil contract in assertion

Fix: Ensure contract is passed through every assertion:

# WRONG - contract not updated
function result = 'modules/tests/assertions/equal',
  contract: contract,
  expected: expected,
  actual: actual,
  field_name: 'test'

# CORRECT - contract reassigned
function contract = 'modules/tests/assertions/equal',
  contract: contract,
  expected: expected,
  actual: actual,
  field_name: 'test'

Object Property Access Errors

Symptom: Cannot access property of nil

Fix: Add presence checks or use blank/presence assertions:

{% liquid
  if user != blank
    function contract = 'modules/tests/assertions/equal',
      contract: contract,
      expected: expected_email,
      actual: user.email,
      field_name: 'user_email'
  else
    function contract = 'modules/tests/helpers/register_error',
      contract: contract,
      field_name: 'user_exists',
      message: 'User object is nil'
  endif
%}

5.3 Debugging with Logs

# Watch logs while running tests
insites-cli logsv2 staging

# In another terminal
insites-cli test run staging test/failing_test

5.4 Debugging with Browser

1. Navigate to /_tests/run?path=test/failing_test
2. Examine HTML output for detailed error messages
3. Check /_tests/run.js?path=test/failing_test for structured JSON errors

Security Constraints

ABSOLUTE RULES - NO EXCEPTIONS:

1. NEVER run tests in production environments
2. The test runner ONLY operates on staging or development
3. Test data MUST be isolated and cleaned up
4. Credentials in tests MUST use environment variables or test fixtures
5. Email testing MUST use test recipients, never real addresses

Verification Checklist

Before committing any test, YOU MUST verify:

• File is in app/lib/test/ directory
• File ends with _test.liquid
• Contract is initialized as first operation
• Contract is returned as last operation
• Every assertion updates the contract variable
• At least one assertion exists
• Test runs successfully via insites-cli test run staging
• Test fails appropriately when expected conditions aren't met
• No hardcoded credentials or production data

Quick Reference Card

File Location

app/lib/test/*_test.liquid

Essential Commands

insites-cli deploy staging              # Deploy before testing
insites-cli test run staging            # Run all tests
insites-cli test run staging test/name  # Run specific test
insites-cli sync staging                # Real-time sync
insites-cli logsv2 staging                # View logs

Browser Endpoints

/_tests                 # List tests
/_tests/run             # Run all tests
/_tests/run?path=X      # Run specific test
/_tests/sent_mails      # View sent emails
/_tests/sent_mails/:id  # View specific email

Test Template

{% liquid
  function contract = 'modules/tests/helpers/init'

  # Setup and execution here

  function contract = 'modules/tests/assertions/equal',
    contract: contract,
    expected: expected_value,
    actual: actual_value,
    field_name: 'test_name'

  return contract
%}

Available Assertions

equal              - Compare two values
blank              - Field is empty/null
presence           - Field exists with value
not_presence       - Field is null/missing
valid_object       - object.valid is true
not_valid_object   - object.valid is not true
invalid_object     - object.valid is falsy
object_contains_object - Object has key-value subset
true               - Value is truthy
not_true           - Value is falsy

Custom Error Registration

function contract = 'modules/tests/helpers/register_error',
  contract: contract,
  field_name: 'identifier',
  message: 'Error description'

Related Skills

• insites-deployment
• liquid-templating
• graphql-queries
• ci-cd-pipelines

References

• Insites Documentation
• insites-cli Documentation