Mojolicious

Mojolicious Development

Use the Mojolicious app script for efficient development and testing.

Core Capabilities

• Search documentation - Search Mojolicious docs using Google Custom Search
• Browse documentation - View official docs at https://docs.mojolicious.org/
• Test requests - Test app endpoints using the built-in commands
• View routes - List all application routes

Documentation Access

Searching Documentation

Use WebSearch with site restriction to search Mojolicious documentation:

WebSearch: "routing guide site:docs.mojolicious.org"
WebSearch: "websocket site:docs.mojolicious.org"

Or use WebFetch with Google Custom Search:

https://www.google.com/cse?cx=014527573091551588235:pwfplkjpgbi&q=<query>

Browsing Documentation

Documentation URLs follow these patterns:

• Mojolicious modules: https://docs.mojolicious.org/Mojolicious/Guides/Routing

  • Use / separators for Mojolicious namespace
  • Example: Mojolicious::Guides::Routing → /Mojolicious/Guides/Routing

• CPAN modules: https://docs.mojolicious.org/Path::To::Module

  • Use :: separators for other modules
  • Example: Mojo::UserAgent → /Mojo::UserAgent

Testing Your Application

Quick Testing

Quick testing is useful for rapid manual verification during development.

Testing Requests

Use the app script for GET requests only. For other HTTP methods (POST, PUT, DELETE), use curl with a running server:

# GET request (use app.pl)
./app.pl get /api/users

# GET request with query parameters (use app.pl)
./app.pl get /api/users?page=1

# GET request with custom headers (use app.pl)
./app.pl get /api/users -H 'Authorization: Bearer token123'

# For POST, PUT, DELETE: Start server first
./app.pl daemon -l http://127.0.0.1:3000

# POST request with JSON data (use curl)
curl -X POST http://127.0.0.1:3000/api/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice","email":"alice@example.com"}'

# PUT request (use curl)
curl -X PUT http://127.0.0.1:3000/api/users/1 \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice Updated"}'

# DELETE request (use curl)
curl -X DELETE http://127.0.0.1:3000/api/users/1

# curl with custom headers
curl http://127.0.0.1:3000/api/users \
  -H 'Authorization: Bearer token123'

Viewing Routes

List all application routes:

./app.pl routes

This shows the routing table with HTTP methods, paths, and route names.

Unit Testing with Test::Mojo

For proper automated testing, use Test::Mojo. It provides a comprehensive testing framework with chainable assertions.

Creating Test Files

Create test files in the t/ directory:

# t/api.t
use Test2::V0;
use Test::Mojo;

# Create test instance
my $t = Test::Mojo->new('path/to/app.pl');

# Test GET request
$t->get_ok('/api/todos')
  ->status_is(200)
  ->json_is([]);

# Test POST request
$t->post_ok('/api/todos' => json => {title => 'Buy milk', completed => 0})
  ->status_is(201)
  ->json_has('/id')
  ->json_is('/title' => 'Buy milk')
  ->json_is('/completed' => 0);

# Test GET specific todo
$t->get_ok('/api/todos/1')
  ->status_is(200)
  ->json_is('/title' => 'Buy milk');

# Test PUT request
$t->put_ok('/api/todos/1' => json => {completed => 1})
  ->status_is(200)
  ->json_is('/completed' => 1);

# Test DELETE request
$t->delete_ok('/api/todos/1')
  ->status_is(200)
  ->json_has('/message');

# Test error cases
$t->get_ok('/api/todos/999')
  ->status_is(404)
  ->json_has('/error');

$t->post_ok('/api/todos' => json => {})
  ->status_is(400)
  ->json_is('/error' => 'Title is required');

done_testing();

Running Tests

# Run all tests
prove -lv t/

# Run specific test file
prove -lv t/api.t

# Run with verbose output
perl t/api.t

Key Test::Mojo Features

• Chainable assertions: Chain multiple assertions for concise tests
• HTTP methods: get_ok, post_ok, put_ok, delete_ok, etc.
• Status assertions: status_is(), status_isnt()
• JSON assertions: json_is(), json_has(), json_like()
• Content assertions: content_like(), content_type_is()
• Header assertions: header_is(), header_like()
• Automatic session management: Cookies are handled automatically
• No server needed: Tests run without starting a real server

Quick Examples

# View all routes in your application
./app.pl routes

# Test a GET endpoint (use app.pl)
./app.pl get /api/users

# Test with authentication header (use app.pl)
./app.pl get /api/protected -H 'Authorization: Bearer mytoken'

# Start server for testing POST/PUT/DELETE
./app.pl daemon -l http://127.0.0.1:3000

# Test a POST endpoint with JSON (use curl)
curl -X POST http://127.0.0.1:3000/api/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Bob","role":"admin"}'

Workflow

1. Plan: Check routes with ./app.pl routes
2. Search: Find relevant documentation for the feature
3. Read docs: Browse official docs at https://docs.mojolicious.org/
4. Implement: Write your code
5. Test:
   • Recommended: Write unit tests with Test::Mojo in t/ directory
   • Quick testing: Use ./app.pl get for GET requests, or curl with daemon for other methods
6. Run tests: Execute with prove -lv t/ to verify all functionality

Guidelines

• Always check ./app.pl routes to understand the current routing structure
• Prefer unit testing over quick testing:
  • Write automated tests with Test::Mojo in t/ directory for reliable, repeatable testing
  • Use quick testing (app.pl/curl) only for rapid manual verification during development
• For quick testing endpoints:
  • GET requests: Use ./app.pl get <path> (no server needed)
  • POST/PUT/DELETE: Start server with ./app.pl daemon and use curl
• Search documentation using site-restricted WebSearch: site:docs.mojolicious.org <query>
• For module documentation, use WebFetch with proper URL patterns:
  • Mojolicious namespace: https://docs.mojolicious.org/Mojolicious/Path
  • Other modules: https://docs.mojolicious.org/Module::Name
• Follow the workflow: plan → search → read docs → implement → unit test → (optional: quick test)
• Test::Mojo provides better test coverage and automation than manual curl commands