Testing

Testing a federated server app is a bit tricky because it requires a federated environment. This document explains how to easily test your federated server app with the help of several tools.

Exposing a local server to the public

To test your federated server app, you need to expose your local server to the public internet with a domain name and TLS certificate. There are several tools that help you do that:

• fedify tunnel
• ngrok
• serveo
• localhost.run
• Tailscale Funnel

NOTE

These tools are not for production use; they are for testing only. In production, you should expose your server with a proper domain and TLS certificate.

TIP

These tools behave like a reverse proxy, so basically the federation server cannot recognize if it is behind a reverse proxy, and if the reverse proxy is in HTTPS. So the federation server will generate HTTP URLs in the ActivityPub messages, which cause interoperability issues.^[1] In this case, you can use the x-forwarded-fetch middleware in front of the Federation.fetch() method so that the Federation object recognizes the proper domain name and protocol of the incoming HTTP requests.

For more information, see How the Federation object recognizes the domain name section in the Federation document.

Inspecting ActivityPub objects

BrowserPub

BrowserPub is a browser for debugging ActivityPub and the fediverse. You can punch in any ActivityPub discoverable web URL or fediverse handle, and it will discover and display the underlying ActivityPub.

For example:

• hollo.social/@fedify
• @hongminhee@fosstodon.org

If you want to know further details about BrowserPub, read the creator's Mastodon thread.

fedify lookup command

Fedify provides a CLI toolchain for testing and debugging. The fedify lookup command is a simple tool for looking up an ActivityPub object by its URL or fediverse handle.

Inspecting ActivityPub activities

ActivityPub.Academy

ActivityPub.Academy is a special Mastodon instance that is designed for debugging and testing ActivityPub peers. You can create an account on it and use it for testing your federated server app. Its best feature is that it provides a web interface for debugging ActivityPub messages. Any sent and received activities are displayed on the web interface in real-time.

NOTE

Any accounts on ActivityPub.Academy are volatile; they are deleted after a certain period of inactivity.

fedify inbox command

Fedify provides a CLI toolchain for testing and debugging. The fedify inbox command is a simple tool for spinning up an ephemeral inbox server that receives and displays incoming ActivityPub messages.

Allowing fetching private network addresses

This API is available since Fedify 0.15.0.

By default, Fedify disallows fetching private network addresses (e.g., localhost) in order to prevent SSRF attacks. However, in some cases, you may want to allow fetching private network addresses for testing purposes (e.g., end-to-end testing). In this case, you can set the allowPrivateAddress option to true in the createFederation() function:

const federation = createFederation({
  // ... other options
  allowPrivateAddress: true,
});

NOTE

By turning on the allowPrivateAddress option, you cannot configure other options related to document loaders including documentLoader, contextLoader, and authenticatedDocumentLoaderFactory

WARNING

Be careful when you allow fetching private network addresses. It may cause security vulnerabilities such as SSRF. Make sure to turn off the option when you finish testing, or conditionally turn it on only in the testing environment.

---

1. According to the Object Identifiers section in the ActivityPub specification, the public dereferenceable URIs should use HTTPS URIs. ↩︎