223 lines
6.3 KiB
Markdown
223 lines
6.3 KiB
Markdown
---
|
|
name: mojolicious
|
|
description: Assist with Mojolicious web framework development using documentation search, browsing, and testing requests without starting a server.
|
|
---
|
|
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```perl
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|