@blocklet/testlab

The @blocklet/testlab provides a comprehensive suite of tools for testing and deploying Blocklets. This library simplifies the process of initializing, deploying, and testing Blocklet applications.

Installation

To get started with the Blocklet Test Library, install the package via npm or pnpm:

npm install @blocklet/testlab

pnpm install @blocklet/testlab

Quick Start

Below are the main steps to use the Blocklet Test Library:

1. Prepare Blocklet Bundle: Ensure you have the Blocklet bundle ready.
2. Create Wallets: Create server, app, and owner wallets.
3. Initialize Test Application: Initialize the test application using the created wallets.
4. Deploy Blocklet: Deploy the Blocklet to the test application.
5. Start Test Application: Start the test application.
6. Set User Data: Optionally, set user data if required (e.g., connecting to DID Space).
7. Get Access URL: Retrieve the access URL for the test application.

Example

Below is an example script demonstrating how to use the Blocklet Test Library:

start-e2e.ts

#!/usr/bin/env -S node -r ts-node/register

import {
  addBlocklet,
  getBlockletServerStatus,
  initTestApp,
  removeTestApp,
  startTestApp,
} from '@blocklet/testlab/utils/server';
import { didToDomain, ensureWallet, types } from '@blocklet/testlab/utils/wallet';
import Joi from 'joi';
import { $, argv } from 'zx';

import { setupUsers } from '../tests/utils/auth';

const ui = argv.ui;

const portSchema = Joi.number<number>().integer().empty(['']);
const blockletCli = process.env.BLOCKLET_CLI || 'blocklet';
const httpPort = (portSchema.validate(process.env.BLOCKLET_SERVER_HTTP_PORT).value as number) || 80;
const httpsPort = (portSchema.validate(process.env.BLOCKLET_SERVER_HTTPS_PORT).value as number) || 443;

(async () => {
  const serverWallet = ensureWallet({ name: 'server' });
  const appWallet = ensureWallet({ name: 'app', role: types.RoleType.ROLE_APPLICATION });
  const ownerWallet = ensureWallet({ name: 'owner' });

  await initTestApp({
    blockletCli,
    serverWallet,
    appWallet,
    ownerWallet,
    httpPort,
    httpsPort,
  });

  await addBlocklet({
    blockletCli,
    appId: appWallet.address,
    bundle: '.blocklet/bundle',
    mountPoint: '/',
  });

  await startTestApp({ blockletCli, appWallet });

  const info = await getBlockletServerStatus();
  if (!info) throw new Error('Blocklet server is not running');

  const appUrl = didToDomain({ did: appWallet.address, port: info.httpsPort });
  process.env.TEST_BLOCKLET_APP_URL = appUrl;

  await setupUsers();

  process.env.PW_TEST_HTML_REPORT_OPEN = 'never';
  await $`playwright test ${ui ? '--ui' : ''}`;

  await removeTestApp({ blockletCli, appSk: appWallet.secretKey });
})();

API Reference

Wallet

• ensureWallet: Create or retrieve a wallet from the cache.

  const serverWallet = ensureWallet({ name: 'server' });
  const appWallet = ensureWallet({ name: 'app', role: types.RoleType.ROLE_APPLICATION });
  const ownerWallet = ensureWallet({ name: 'owner' });

• claimTokens: Retrieve test tokens for a wallet.

  await claimTokens({ wallet: ownerWallet });

• didToDomain: Get the DID Domain for a Blocklet container.

  const appUrl = didToDomain({ did: appWallet.address, port: info.httpsPort });

Server

• initTestApp: Initialize a Blocklet container for testing.

  await initTestApp({
    serverWallet,
    appWallet,
    ownerWallet,
  });

• addBlocklet: Deploy a Blocklet to a Blocklet container.

  await addBlocklet({
    appId: appWallet.address,
    bundle: '.blocklet/bundle',
    mountPoint: '/',
  });

• startTestApp: Start a Blocklet container.

  await startTestApp({ blockletCli, appWallet });

• removeTestApp: Remove a Blocklet container.

  await removeTestApp({ blockletCli, appSk: appWallet.secretKey });

• getBlockletServerStatus: Retrieve the status of the Blocklet server.

  const info = await getBlockletServerStatus();

Authentication

• claimVC: Claim a VC.

  const vc = await claimVC({ authUrl, wallet });

• showAssetOrVC: Present a VC.

  await showAssetOrVC({ authUrl, wallet, vc, meta: { purpose: 'DidSpace' } });

Playwright

• getAuthUrl: Retrieve the authentication URL from the DID Connect dialog.

  const authUrl = await getAuthUrl({ page });

• login: Simulate user login for DID Connect.

  await login({ page, wallet });

• logout: Simulate user logout.

  await logout({ page });

• claimDIDSpace: Claim a DID Space.

  const vc = await claimDIDSpace({ page, wallet });

This document provides all the essential steps and API references to get started with the Blocklet Test Library. We hope this helps you efficiently test and deploy your Blocklet applications.