🌳 Treetracker Wallet App

Secure and user-friendly digital token management platform built by Greenstand

Greenstand offers a secure, user-friendly wallet for seamless token transfers, built with enterprise-grade security and a scalable monorepo architecture supporting web, mobile, and backend services.

Treetracker Wallet App is part of the Greenstand ecosystem, enabling transparent and verifiable tree planting and forest management through blockchain technology.

⚡ Quick Start

Prerequisites

• Node.js (v20 or higher)
• Yarn (v1.22 or higher)
• Docker (for backend development)

🚀 One-Command Setup

# Clone, and install dependencies, and start development
git clone https://github.com/Greenstand/treetracker-wallet-app.git
cd treetracker-wallet-app && yarn install

🏃‍♂️ Start Development

Option 1: Quick Web Development

yarn web:dev
# Opens http://localhost:3000

Option 2: Full Stack Development

# Terminal 1: Start backend API
yarn user:dev

# Terminal 2: Start web application
yarn web:dev

# Terminal 3: Start mobile app
yarn native:start

🧪 Testing

# Run E2E tests (recommended for understanding the project)
yarn cypress-e2e-test

# Or run headless tests
yarn cypress-e2e-headless-test

💡 Tip: Run the E2E tests to understand what this project does and how the apps work together!

Behavior Driven Development (BDD)

🚀 Overview

Added comprehensive end-to-end testing using WebdriverIO for the wallet application, covering:

• ✅ Login flow (success & failure cases)
• ✅ Wallet creation process
• ✅ User registration workflow
• ✅ HTML test reports with detailed execution analysis
• ✅ Video recordings for debugging failed tests
• and more

---

🧪 Test Commands

Run these from the repository root:

# Run all E2E tests
yarn bdd:e2e

# Run specific test suite
yarn bdd:e2e:login
yarn bdd:e2e:register
yarn bdd:e2e:wallet

# Debug mode (verbose output)
yarn bdd:e2e:debug

# Update ChromeDriver (if tests fail)
yarn bdd:e2e:update-driver

# Generate HTML test reports
yarn bdd:report          # Generate HTML report from existing test results
yarn bdd:test:report     # Run tests + generate HTML report

---

🖼️ Test Evidence

Sample Output:

$ yarn test:e2e
[chrome] ✔ Login - Valid credentials (4.2s)
[chrome] ✔ Wallet Creation - Basic flow (6.1s)
[chrome] ✔ Registration - Email signup (5.8s)

HTML Test Reports:

• Detailed execution analysis with pass/fail status
• Video recordings for debugging failed tests
• Browser metadata and execution timing
• Generated in apps/bdd/reports/cucumber-html/index.html

---

✅ Verification Checklist

• All tests pass locally (yarn test:e2e)
• HTML reports generated successfully (yarn bdd:report)
• Video recordings captured for failed tests
• No production code modified
• Test data follows PII guidelines
• ChromeDriver version (v136) matches CI
• Documentation updated if needed

---

⚠️ Requirements

The backend must be running for the tests to function. You can start it with:

yarn workspace web dev

Also, ensure you have Chrome v136+ installed.

How to develop BDD E2E test

A recommended way to develop e2e test by practicing TDD method, basically it use watch mode to auto-rerun the test once you changed the file, and use the browser.debug() to set stop point, so you can enter the REPL mode to try and verify things.

About REPL.

Now assume that we will deploy a scenario of create wallet, run command:

cd apps/bdd
npx wdio run ./wdio.debug.conf.ts --watch  --spec ./features/create-wallet.feature:26

The wdio.debug.conf.ts has some settings that are convenient for debug, longer timeout, no headless mode, etc.

Use --spec to specify the file of feature, and the line of the scenario, so only this scenario will be run.

Now it will run the scenario and finish it, but still keep the window open, you can modify the scenario then save it, the test will be re-run automatically.

When the test run to the browser.debug() line, it will pause and enter the REPL mode, you can try commands in the terminal, now you can run any webdriverIO command to verify things, see doc here: https://webdriver.io/docs/api

NOTE, there are still some problem with this approach:

1. The WebdriverIO watch mode can not JUST monitor the feature files, that means, if you want to rerun the test, you have to save or touch the feature file to trigger rerun. Reason

2. If stop at browser.debug(), then you can not re-run directly, you need to quit (by ctrl+c) the REPL mode, then save the feature file to trigger rerun.

🏗️ Project Structure

treetracker-wallet-app/
├── apps/
│   ├── web/             # Next.js 14 web application
│   ├── native/          # React Native mobile app (Expo)
│   ├── user/            # NestJS backend API service
│   └── bdd/             # BDD E2E tests (WebdriverIO + Cucumber)
├── packages/
│   ├── core/            # Shared business logic (jotai)
│   └── queue/           # Message queue utilities

🚀 Development Guide

Ready to contribute? Here's your path from setup to deployment:

1. Fork the repository on GitHub

1. Initial Setup

git clone https://github.com/YOUR_USERNAME/treetracker-wallet-app.git
cd treetracker-wallet-app
yarn install

2. Choose Your Development Path

🌐 Web Development

Perfect for UI/UX improvements and frontend features

yarn web:dev
# → http://localhost:3000

📱 Mobile Development

For cross-platform mobile features

yarn native:start
# → Scan QR code with Expo Go app

🔧 Backend Development

For API development and database work

# Setup environment (first time only)
cp apps/user/.env.example apps/user/.dev.env
# → Edit .dev.env with your configuration

yarn user:dev
# → http://localhost:8080

3. Full Stack Development

Run all services for integrated development:

# Individual terminals
yarn web:dev     # Terminal 1
yarn user:dev    # Terminal 2
yarn native:start # Terminal 3

🧪 Testing & Quality

Quick Testing

# E2E tests (best way to understand the project)
yarn cypress-e2e-test

# Headless testing
yarn cypress-e2e-headless-test

# Unit tests
yarn test

# Lint and format
yarn lint:fix

## Commit hooks and test behavior

We run `lint-staged` on commit to keep commits fast. Heavy integration/unit/e2e
tests are not run during commit — they run in CI on pull requests instead.

Note: this repository uses Yarn v4 via Corepack. If you see a message about
Yarn versions, run:

```bash
corepack enable
corepack prepare yarn@4.9.4 --activate
yarn -v  # should show a Yarn 4.x version

## How to set up: lint, code format, Typescript for a new package/app

Follow this PR too add shared configuration package to standardize linting,
formatting, and TypeScript setup across the project.

https://github.com/Greenstand/treetracker-wallet-app/pull/537/files

## 🤝 Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or
improving documentation, your help makes Treetracker better.

**👉 [Read our full Contributing Guide →](./CONTRIBUTING.md)**

The contributing guide covers everything you need: setup, workflows, coding
standards, testing, and review processes.

## 🤝 Community & Support

### **Get Help**

- **Documentation:** Start with this README and
  [Contributing Guide](./CONTRIBUTING.md)
- **Issues:** Report bugs and request features on
  [GitHub Issues](https://github.com/Greenstand/treetracker-wallet-app/issues)
- **Slack:** Join our Slack community (Ask the maintainers for an invite)
- **Discussions:** Ask questions in Slack

<!-- trigger -->