Testing Fuselage Components

Reliable testing is essential to ensure the stability, performance, and correctness of Fuselage components. This guide outlines the testing strategies used in Rocket.Chat and provides practical approaches for validating packages during development.

When tools such as Storybook or local previews are not sufficient, additional techniques can be used to test components in real application environments.

Recommended repository structure

The examples in this guide assume a workspace where the Fuselage repository and the Rocket.Chat application are located as sibling directories:

- fuselage
  - .git
  - packages
    - ...on
  - ...
- Rocket.Chat
  - .git
  - apps
    - meteor
      - ...
    - ...
  - ...

This setup enables efficient linking, dependency updates, and local package testing. This structure serves as the foundation for the techniques described below.

Technique 1: yarn fuselage script

To simplify package testing and dependency management, Fuselage provides a helper script accessible through:

yarn fuselage -a [action] -p [package]

Targeting packages

Use the -p (or --package) flag to specify one or more packages. Multiple packages can be provided as a semicolon-separated list:

[package1;package2]

Example usages

Create symbolic links for multiple packages:

yarn fuselage -a link -p fuselage;fuselage-icons;message-parser

yarn fuselage -a undo

yarn fuselage -a latest -p fuselage

Update all Fuselage dependencies:

yarn fuselage -a latest-all

When to use this script

Use the yarn fuselage script when you want to:

• Test local changes without publishing packages

• Debug integration issues inside Rocket.Chat

• Quickly update dependencies

• Validate packages before creating a pull request

Technique 2: Using yarn’s link: protocol

The link: protocol allows you to reference a local package directly from your filesystem instead of installing it from npm. This is especially useful when developing Fuselage locally and testing changes inside the Rocket.Chat project in real time.

Unlike yarn link, the link: protocol avoids workspace resolution issues and provides a more predictable dependency setup.

Add link

Follow these steps to connect your local Fuselage package to Rocket.Chat.

1. Run webpack in watch mode: Start the development build so changes in Fuselage are continuously compiled:

   cd fuselage/packages/fuselage
   yarn start
   cd -

2. Add a relative path resolution: Open the root package.json file in Rocket.Chat and add a resolution pointing to your local package:

   {
     "resolutions": {
       "@rocket.chat/fuselage": "link:../fuselage/packages/fuselage"
     }
   }

3. Update dependencies: Reinstall dependencies so Yarn applies the new resolution:

   cd Rocket.Chat
   yarn
   cd -

Rocket.Chat will now consume your local Fuselage build.

Remove link

When you are finished testing, revert back to the published package:

cd Rocket.Chat
yarn unlink --all ../fuselage
cd -

You should also remove the resolutions entry from package.json and run yarn again.

yarn link ../fuselage/packages/fuselage                                                                                                                                                                                    26581ms 
➤ YN0000: ┌ Resolution step
➤ YN0001: │ Error: @rocket.chat/css-in-js@workspace:~: Workspace not found (@rocket.chat/css-in-js@workspace:~)
    at ze.getWorkspaceByDescriptor (/Users/tasso/Projetos/Rocket.Chat/.yarn/releases/yarn-3.2.0.cjs:441:3273)
    at md.getCandidates (/Users/tasso/Projetos/Rocket.Chat/.yarn/releases/yarn-3.2.0.cjs:394:29907)
    at wd.getCandidates (/Users/tasso/Projetos/Rocket.Chat/.yarn/releases/yarn-3.2.0.cjs:395:1281)
    at wd.getCandidates (/Users/tasso/Projetos/Rocket.Chat/.yarn/releases/yarn-3.2.0.cjs:395:1281)
    at /Users/tasso/Projetos/Rocket.Chat/.yarn/releases/yarn-3.2.0.cjs:441:7765
    at Pg (/Users/tasso/Projetos/Rocket.Chat/.yarn/releases/yarn-3.2.0.cjs:394:11098)
    at le (/Users/tasso/Projetos/Rocket.Chat/.yarn/releases/yarn-3.2.0.cjs:441:7745)
➤ YN0000: └ Completed in 0s 391ms
➤ YN0000: Failed with errors in 0s 398ms

Technique 3: Using symbolic links in node_modules

This technique allows you to test local changes to a Fuselage package directly inside the Rocket.Chat repository by creating a symbolic link (symlink). The symlink replaces the installed package with your local version, enabling real-time testing without publishing updates.

When to use this script

Use this method when:

• You want direct control over a specific Fuselage package

• You are debugging package-level issues

• The link: protocol is not suitable for your setup

• You need a quick, manual override of an installed dependency

Install dependencies and build packages

From the Rocket.Chat repository root, install dependencies and build the project:

yarn && yarn build

Create the symbolic link

Navigate to the directory where Rocket.Chat installs Fuselage packages and replace the installed package with a symlink pointing to your local version.

yarn && yarn build

cd apps/meteor/node_modules/@rocket.chat # To find meteor node_modules/@rocket.chat directory where the fuselage packages are installed

rm -rf {package} # Where {package} is the name of fuselage package, e.g: fuselage, message-parser, ui-kit, icons and others...

ln -s ../../../../../fuselage/packages/{package} ./{package} # Where {package} is the name of fuselage package and the path needs to aligned to your project location

yarn dsv

Once the server starts, your application should reflect the local changes.