Part 4: Test your module locally

Part 4 of 5 | ⏱️ 20 minutes

What you’ll do in this part

• Add your module to a test machine using hot reload
• Configure your camera component
• Test the camera in the Viam app
• Learn the iteration workflow
• Troubleshoot common issues

You can test your module locally before uploading it to the registry.

Test with hot reload (recommended)

Hot reload is the fastest way to test your module. It automatically builds your module and deploys it to your machine for testing.

Add module to your machine

Run the following command from your module directory to build and deploy your module:

viam module reload-local --cloud-config /path/to/viam.json

viam module reload --part-id 123abc45-1234-432c-aabc-z1y111x23a00

For more information, see the viam module CLI documentation.

The command will:

1. Build your module using your local architecture or the target machine’s architecture
2. Package it with all dependencies
3. Use the shell service to copy it to your machine
4. Restart the module automatically

viam module reload --part-id YOUR_PART_ID --home /Users/yourname/

Configure your component

Now that your module is added to your machine, configure a component that uses it:

1. On your machine’s CONFIGURE page, click +
2. Select Local module, then Local component
3. Enter the model namespace triplet, for example: exampleorg:hello-world:hello-camera
   • You can find this in the model field of your meta.json file
4. Select Camera as the Type
5. Enter a Name, such as camera-1
6. Click Create

Add configuration attributes

In the configuration panel that appears, add your model’s required attributes.

For the camera model, replace {} with:

{
  "image_path": "/path/to/your/image.png"
}

Replace /path/to/your/image.png with an actual path to an image file on your machine.

Save the config and wait a few seconds for it to apply.

Test your component

Click the TEST section at the bottom of your camera’s configuration card.

If everything is working correctly, you should see your image displayed in the test panel!

If you see errors

Errors will appear in:

• The configuration panel (red banner)
• The LOGS tab (click LOGS in the top navigation)

Common issues:

• “Missing image_path attribute”: Add image_path to your config JSON
• “Error opening image”: Check that the file path is correct and readable
• Module not found: Refresh the page or restart the module

Iterate on your module

Each time you make changes to your module code, update it on your machine:

• Hot reload (recommended)
• Manual testing

Run the reload command again:

• Same device
• Other device

viam module reload-local --cloud-config /path/to/viam.json

viam module reload --part-id 123abc45-1234-432c-aabc-z1y111x23a00

Your machine may already have a previously published version of the module you’re iterating on. If so, you can toggle Hot Reloading on and off in the module’s configuration card in the Viam app:

• On: Uses your local development version
• Off: Uses the published registry version

• Python
• Go

Save your code changes, then restart the module in your machine’s CONFIGURE tab:

1. Find the module’s card
2. Click the … menu in the upper-right corner
3. Click Restart

1. Rebuild your module:

   viam module build local
   

2. Restart it in your machine’s CONFIGURE tab:

   • Find the module’s card
   • Click the … menu
   • Click Restart

Development workflow

The typical development cycle:

1. Edit code in your module files
2. Reload/restart the module on your machine
3. Test using the TEST panel or Viam app
4. Check logs if something doesn’t work
5. Repeat until it works as expected

What you’ve accomplished

✅ Module deployed:

• Used hot reload to build and deploy your module
• Module running on a real machine

✅ Component configured:

• Added camera component with proper configuration
• Verified configuration validation works

✅ Testing complete:

• Tested camera in Viam app
• Confirmed images are returned correctly

✅ Ready for more:

• Understand the iteration workflow
• Know how to debug issues

Next steps

Your module works! Now you have two options:

1. Ready to deploy? Once you’ve thoroughly tested your module, continue to Package and deploy your module to upload it to the registry
2. Want to add more models? Continue to Part 5: Multiple models to learn how to add the sensor model to your module

Tutorial navigation:

• Previous: ← Part 3: Implement your module
• Current: Part 4: Test your module locally
• Next: Part 5: Multiple models (advanced) → or Deploy to registry →
• All parts: Module creation tutorial