Test Environment

Beyond interactive development with blocklet dev, the Blocklet Server CLI provides a dedicated, ephemeral environment for running automated tests. This ensures your blocklet is tested in a clean, isolated, and repeatable context, which is essential for continuous integration and reliable deployments.

The primary command for this workflow is blocklet test.

The blocklet test Command#

This command automates the entire testing lifecycle for a blocklet. When you run blocklet test, it performs the following steps:

1. Environment Setup: It starts a temporary, isolated instance of Blocklet Server.
2. Blocklet Installation: It bundles and installs your current blocklet project into this temporary server.
3. Test Execution: It runs the test script defined in your blocklet's package.json file (typically npm test).
4. Cleanup: After the tests complete, it automatically shuts down and cleans up the temporary server and any installed assets.

This process guarantees that your tests run against the exact version of the code you're working on, free from any state or configuration from previous development sessions.

Basic Usage#

To run your blocklet's test suite, navigate to your project's root directory and execute:

Ensure you have a test script defined in your package.json:

Command Options#

You can customize the test environment's behavior with several options:

Option	Description
--server-did <did>	Specify a DID to use an existing Blocklet Server instance instead of creating a temporary one. Useful for tests against a pre-configured server.
--mount-point <path>	Set a custom mount point for the blocklet within the test server (e.g., /my-test-app).
--app-did <did>	Assign a specific DID to the blocklet being tested.
--chunk-prefix <prefix>	Specify a custom prefix for asset chunks.

Example with options:

This command runs tests using an existing server and mounts the blocklet at /custom-path.

Test Environment vs. Develop Mode#

It's important to understand the distinction between blocklet test and blocklet dev:

• blocklet dev:
• • Purpose: Designed for interactive development.
  • Environment: Stateful and long-running, allowing you to manually test changes in real-time.
  • Features: Establishes a persistent connection to your development server and enables features like hot-reloading.
• blocklet test:
• • Purpose: Designed for automated testing.
  • Environment: Creates a fresh, stateless environment for every run and is ephemeral, ensuring each test run is isolated.
  • Features: Executes a predefined test script and then cleans up automatically.

Use blocklet dev when you are actively writing code and visually checking your work. Use blocklet test in your CI/CD pipeline or whenever you need to validate your blocklet's functionality automatically.

After thoroughly testing your blocklet, the next step is to prepare it for distribution. Proceed to the Packaging & Versioning section to learn how to bundle and version your project.