Skip to content

README.md

Latest commit

 

History

History
264 lines (180 loc) · 7.29 KB

README.md

File metadata and controls

264 lines (180 loc) · 7.29 KB

Lint Test built with garnix Status

Logo
libXMTP

shared library encapsulating the core functionality of the XMTP messaging protocol, such as cryptography, networking, and language bindings.
Documentation · Contributing

Requirements

Development

Adding Dependencies

  • adding dependencies will require re-generating the workspace-hack crate, which can be done with:
nix develop --command cargo hakari generate

to verify correctness you can optionally run

nix develop --command cargo hakari verify

Start Docker Desktop.

  • To install other dependencies and start background services:

    ./dev/up

    Specifically, this command creates and runs an XMTP node in Docker Desktop.

  • This project uses just as a command runner. Run just to list all available recipes, including submodules for Android, iOS, Node.js, and WASM:

    just          # List all recipes
just format   # Format code
just lint     # Run all linting

  • To run tests:

    RUST_LOG=off cargo test

    Many team members also install and use cargo nextest for better test isolation and log output behavior.

  • run tests and open coverage in a browser:

./dev/test/coverage

  • To run WebAssembly tests headless:

    just wasm test

Note: If the tests fail with "bind() failed: Cannot assign requested address," Chrome is unable to bind to IPv6 and will fall back to IPv4. Although this should be a warning, Chromedriver currently logs this message as SEVERE, which halts the wasm-bindgen-test. You can optionally disable the Chromedriver logs output to prevent this.

CHROMEDRIVER_ARGS="--log-level=OFF" just wasm test

  • To run WebAssembly tests interactively for a package, for example, xmtp_mls:

    ./dev/test/wasm-interactive xmtp_mls

  • To run browser SDK tests:

    ./dev/test/browser-sdk

Tips & Tricks

Log Output Flags for Tests

  • Output test logs in a async-aware context-specific tree format with the environment variable CONTEXTUAL
CONTEXTUAL=1 cargo test
  • Filter tests logs by Crate
RUST_LOG=xmtp_mls=debug,xmtp_api=off,xmtp_id=info cargo test
  • Output test logs as in a structured JSON format for inspection with third-party viewer
STRUCTURED=1 cargo test
  • Two ways to replace InboxIds/InstallationIds/EthAddresses with a human-readable string name in logs

NOTE: Only works when using CONTEXTUAL=1 flag. So to get the replacement, CONTEXTUAL=1 cargo test

1.)

Before the test runs, add an TestLogReplace declaration to the top replace.add accepts two arguments: the string to replace in logs and the string to replace it with. Note that on dropping the "TestLogReplace" object, the replacements will no longer be made.

let mut replace = TestLogReplace::default();
replace.add(alix.installation_id(), "alix_installation_id");

2.) Build the TesterBuilder with_name

let tester = Tester::builder().with_name("alix").build().await;

This replaces all instances of alix's InboxIds, InstallationIds and Identifiers with "alix", "alix_installation", "alix_identifier" respectively, in test output logs.

Quick Start (Dev Containers)

This project supports containerized development. From Visual Studio Code Dev Containers extension specify the Dockerfile as the target:

Reopen in Container

or

Command line build using docker

docker build . -t libxmtp:1

Quick Start (nix)

This project supports Determinate Nix for reproducible development environments. Nix provides pinned toolchains for Rust, Android, iOS, WebAssembly, and Node.js builds.

./dev/nix-up    # One-time setup: install Determinate Nix + direnv + binary caches
nix develop     # Enter the default dev shell

To temporarily disable/enable direnv without uninstalling anything:

./dev/direnv-down  # Disable direnv auto-activation
./dev/direnv-up    # Re-enable direnv

See docs/nix-setup.md for the full setup guide, including binary cache configuration, available dev shells, and direnv usage.

Structure

libxmtp/

├ apps/

│ ├ android: Example Android app (in progress)

│ ├ cli: Example XMTP console client. Use the CLI to try out sending double ratchet messages on the XMTP dev network.

│ └ mls_validation_service: MLS validation service

├ bindings/

│ ├ mobile: FFI bindings for Android and iOS

│ ├ node: Node.js bindings

│ └ wasm: WebAssembly bindings

├ crates/

│ ├ xmtp_api_grpc: API client for XMTP's gRPC API

│ ├ xmtp_cryptography: Cryptographic operations

│ ├ xmtp_mls: Version 3 of XMTP which implements Messaging Layer Security

│ └ xmtp_proto: Generated code for handling XMTP protocol buffers

├ sdks/

│ └ android: Android SDK (Kotlin)

Run the benchmarks

possible benchmarks include:

  • group_limit: benchmarks surrounding maximum members adding/removed from group
  • crypto: benchmarks surrounding cryptographic functions

Example Commands

  • Run a specific category of benchmark cargo bench --features bench -p xmtp_mls --bench group_limit
  • Run against dev grpc DEV_GRPC=1 cargo bench --features bench -p xmtp_mls --bench group_limit
  • Just run all benchmarks ./dev/bench
  • Run one specific benchmark ./dev/bench add_1_member_to_group
  • Generate flamegraph from one benchmark ./dev/flamegraph add_1_member_to_group

Code Coverage

Code coverage is generated using cargo llvm-cov and is integrated into ci and reported to codecov.

To run the tests locally you can run the dev/llvm-cov script to run the same workspace tests and generate both an lcov and html report.

If you have installed the Coverage Gutters extension in vscode (or a derivative) you can get coverage information in your IDE.

Contributing

See our contribution guide to learn more about contributing to this project.