From e2273e94cbef3456b7eac4f7b233daf351ade506 Mon Sep 17 00:00:00 2001 From: Roo Code Date: Tue, 23 Dec 2025 22:59:49 +0000 Subject: [PATCH 1/2] fix: correct corrupted README.md and CONTRIBUTING.md documentation --- CONTRIBUTING.md | 343 +++++++++++++++++++++++++++++++++++++----------- README.md | 234 +++++++++++++++++++++++++-------- 2 files changed, 446 insertions(+), 131 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff3d740..1a0fe20 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,110 +1,295 @@ -# Contributing +# Contributing to OnChainTestKit -All contributions are welcome, from the tiniest typo to a brand new article. -Translations in all languages are welcome (or, for that matter, original -articles in any language). Send a pull request or open an issue any time of day -or night. +Thank you for your interest in contributing to OnChainTestKit! We welcome contributions from the community. -**Please prepend the tag `[language/lang-code]` to your issues and pull -requests.** For example, `[python/en]` for English Python. This will help -everyone pick out things they care about. +## ๐Ÿš€ Getting Started -We're happy for any contribution in any form, but if you're making more than one -major change (i.e. translations for two different languages) it would be super -cool of you to make a separate pull request for each one so that someone can -review them more effectively and/or individually. +### Prerequisites -## Style Guidelines +- Node.js 14.0.0 or higher +- npm, yarn, or pnpm +- Git +- Playwright Test -* **Keep lines under 80 chars** - * Try to keep line length in code blocks to 80 characters or fewer. - * Otherwise, the text will overflow and look odd. - * This and other potential pitfalls to format the content consistently are - identified by [markdownlint](https://github.com/markdownlint/markdownlint). -* **Prefer example to exposition** - * Try to use as few words as possible. - * Code examples are preferred over exposition in all cases. -* **Eschew surplusage** - * We welcome newcomers, but the target audience for this site is programmers - with some experience. - * Try to avoid explaining basic concepts except for those specific to the - language in question. - * Keep articles succinct and scannable. We all know how to use Google here. -* **Use UTF-8** +### Setup Development Environment -### Header configuration +1. **Fork and clone the repository** -The actual site generates HTML files from these Markdown ones. -The markdown files can contain extra metadata before the actual markdown, -called frontmatter. +```bash +git clone https://github.com/YOUR-USERNAME/https-github.com-joe10832-onchaintestkit.git +cd https-github.com-joe10832-onchaintestkit +``` -The following fields are necessary for English articles about programming -languages: +2. **Install dependencies** -* `name`: The human-readable name of the programming language -* `contributors`: A list of [*author*, *URL*] lists to credit, *URL* is optional +```bash +npm install +``` -Other fields: +3. **Build the project** -* `category`: The category of the article. So far, can be one of *language*, - *tool* or *Algorithms & Data Structures*. Defaults to *language* if omitted. -* `filename`: The filename for this article's code. It will be fetched, mashed - together, and made downloadable. +```bash +npm run build +``` -Translations should also include: +4. **Prepare wallet extensions** -* `translators`: A list of [*translator*, *URL*] lists to credit, *URL* is optional +```bash +npm run prepare-metamask +npm run prepare-coinbase +npm run prepare-phantom +``` -Non-English articles inherit frontmatter values from the English article (if it exists) -but you can overwrite them. +5. **Set up environment variables** -Here's an example header for Ruby: +```bash +export E2E_TEST_SEED_PHRASE="test test test test test test test test test test test junk" +``` -```yaml ---- -name: Ruby -filename: learnruby.rb -contributors: - - ["Doktor Esperanto", "http://example.com/"] - - ["Someone else", "http://someoneelseswebsite.com/"] ---- +โš ๏ธ **Never use real seed phrases or funds for testing!** + +6. **Run tests** + +```bash +npm test ``` -### Syntax highlighter +## ๐Ÿ”„ Development Workflow -[Pygments](https://pygments.org/languages/) is used for syntax highlighting. +### 1. Create a Feature Branch -### Should I add myself as a contributor? +Always create a new branch for your changes: -If you want to add yourself to contributors, keep in mind that contributors get -equal billing, and the first contributor usually wrote the whole article. Please -use your judgment when deciding if your contribution constitutes a substantial -addition or not. +```bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/your-bug-fix +``` + +### 2. Make Your Changes + +- Write clean, maintainable code +- Follow the existing code style and patterns +- Add tests for new features or bug fixes +- Update documentation as needed + +### 3. Test Your Changes + +```bash +# Run all tests +npm test + +# Run linting +npm run lint + +# Fix linting issues +npm run lint:fix + +# Format code +npm run format +``` -## Building the site locally +### 4. Commit Your Changes -Install Python. On macOS this can be done with [Homebrew](https://brew.sh/). +Use conventional commit messages: -```sh -brew install python +```bash +git add . +git commit -m "feat: add new wallet support" +# or +git commit -m "fix: resolve connection timeout issue" +# or +git commit -m "docs: update installation guide" +``` + +#### Commit Message Format + +Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +- `feat:` - New feature +- `fix:` - Bug fix +- `docs:` - Documentation changes +- `style:` - Code style changes (formatting, etc.) +- `refactor:` - Code refactoring +- `test:` - Test changes +- `chore:` - Maintenance tasks + +### 5. Push to Your Fork + +```bash +git push origin feature/your-feature-name +``` + +### 6. Create a Pull Request + +1. Go to the [repository](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit) +2. Click "New Pull Request" +3. Select your branch +4. Fill in the PR template with details about your changes +5. Submit the pull request + +## ๐Ÿ“ Code Style Guidelines + +### TypeScript/JavaScript + +- Use TypeScript for all new code +- Follow the existing code structure and patterns +- Use meaningful variable and function names +- Add JSDoc comments for public APIs +- Keep functions small and focused +- Avoid unnecessary complexity + +### Code Quality + +- **Write tests**: All new features should include tests +- **Type safety**: Leverage TypeScript's type system +- **Error handling**: Handle errors appropriately +- **Documentation**: Update docs for API changes +- **Performance**: Consider performance implications + +### File Organization + +``` +src/ +โ”œโ”€โ”€ cli/ # CLI tools and scripts +โ”œโ”€โ”€ contracts/ # Smart contract management +โ”œโ”€โ”€ node/ # Local node and network interceptor +โ”œโ”€โ”€ utils/ # Utility functions +โ”œโ”€โ”€ wallets/ # Wallet implementations +โ”‚ โ”œโ”€โ”€ BaseWallet.ts +โ”‚ โ”œโ”€โ”€ Coinbase/ +โ”‚ โ”œโ”€โ”€ MetaMask/ +โ”‚ โ””โ”€โ”€ Phantom/ +โ””โ”€โ”€ index.ts # Main exports ``` -Then clone two repos, install dependencies and run. +## ๐Ÿงช Testing Guidelines -```sh -# Clone website -git clone https://github.com/adambard/learnxinyminutes-site -# Clone docs (this repo) nested in website -git clone https://github.com//learnxinyminutes-docs ./learnxinyminutes-site/source/docs/ +### Writing Tests -# Install dependencies -cd learnxinyminutes-site -pip install -r requirements.txt +- Place tests in the `tests/` directory +- Mirror the `src/` structure +- Use descriptive test names +- Test edge cases and error conditions +- Keep tests independent and isolated -# Run -python build.py -cd build -python -m http.server +### Test Structure -# open http://localhost:8000/ in your browser of choice +```typescript +import { test, expect } from '@playwright/test'; +import { configure, createOnchainTest } from '@coinbase/onchaintestkit'; + +test.describe('Feature Name', () => { + test('should do something specific', async () => { + // Arrange + const config = configure() + .withMetaMask() + .build(); + + // Act + const result = await someFunction(); + + // Assert + expect(result).toBe(expected); + }); +}); ``` + +## ๐Ÿ“š Documentation + +### Updating Documentation + +When making changes, update relevant documentation: + +- **README.md** - Main project overview +- **docs/** - Detailed guides and API reference +- **Code comments** - Inline documentation +- **Examples** - Usage examples in `example/` + +### Documentation Style + +- Be clear and concise +- Include code examples +- Explain the "why" not just the "what" +- Keep examples up to date +- Use proper markdown formatting + +## ๐Ÿ› Reporting Bugs + +### Before Submitting + +1. Check existing issues to avoid duplicates +2. Test with the latest version +3. Verify it's not a configuration issue + +### Bug Report Template + +Include: + +- **Description**: Clear description of the bug +- **Steps to Reproduce**: Detailed steps to reproduce +- **Expected Behavior**: What should happen +- **Actual Behavior**: What actually happens +- **Environment**: OS, Node version, package version +- **Code Sample**: Minimal reproducible example + +## ๐Ÿ’ก Suggesting Features + +We welcome feature suggestions! Please: + +1. Check if the feature already exists or is planned +2. Open an issue with the `enhancement` label +3. Describe the use case and benefits +4. Provide examples of how it would work + +## ๐Ÿ” Code Review Process + +### What We Look For + +- **Correctness**: Does it work as intended? +- **Tests**: Are there adequate tests? +- **Documentation**: Is it well documented? +- **Style**: Does it follow our guidelines? +- **Performance**: Are there performance implications? +- **Security**: Are there security concerns? + +### Review Timeline + +- Initial review: Within 1-3 business days +- Feedback incorporated: Review continues +- Approved: Ready to merge + +## ๐Ÿšซ What NOT to Contribute + +Please avoid: + +- โŒ Breaking changes without discussion +- โŒ Large refactors without prior approval +- โŒ Code that fails tests or linting +- โŒ Unrelated changes in a single PR +- โŒ Commits with real secrets or credentials + +## ๐Ÿ“ž Getting Help + +Need help with your contribution? + +- ๐Ÿ’ฌ Open a [discussion](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/discussions) +- ๐Ÿ“ง Ask questions in your PR +- ๐Ÿ“– Check the [documentation](./docs/) +- ๐Ÿ› Open an [issue](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues) + +## ๐ŸŽ‰ Recognition + +Contributors will be: + +- Listed in the project's contributors +- Credited in release notes (for significant contributions) +- Part of a growing community of blockchain testing enthusiasts + +## ๐Ÿ“„ License + +By contributing, you agree that your contributions will be licensed under the MIT License. + +--- + +Thank you for contributing to OnChainTestKit! Every contribution, no matter how small, helps make blockchain testing better for everyone. ๐Ÿš€ diff --git a/README.md b/README.md index 10b6d04..4675c4a 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,220 @@ -Formatting.**# Project Title +# OnChainTestKit -## Quickstart +[![npm version](https://img.shields.io/npm/v/@coinbase/onchaintestkit.svg)](https://www.npmjs.com/package/@coinbase/onchaintestkit) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -Instructions on how to quickly get started with this project. +**OnChainTestKit** is an end-to-end testing toolkit for blockchain applications, powered by Playwright. It provides comprehensive testing utilities for Web3 applications with native wallet support. -## Why use +## ๐Ÿš€ Features -Reasons to use this project. +- ๐Ÿ”— **Blockchain Testing**: Complete E2E testing for blockchain applications +- ๐ŸŽญ **Playwright Integration**: Built on Playwright for reliable automation +- ๐Ÿ” **Multiple Wallets**: Native support for MetaMask, Coinbase Wallet, and Phantom +- ๐ŸŒ **Network Support**: Test on mainnet, testnets, or local nodes with fork mode +- ๐Ÿ› ๏ธ **Easy Configuration**: Simple, chainable configuration API +- ๐Ÿ“ **TypeScript Support**: Full TypeScript definitions included -## Getting Commercial Support +## ๐Ÿ“ฆ Installation -Information on how to get commercial support for this project. +Install OnChainTestKit using your preferred package manager: -## Contribute +```bash +# npm +npm install @coinbase/onchaintestkit -Guidelines on how to contribute to this project. +# yarn +yarn add @coinbase/onchaintestkit -- **Write and maintain documentation (`README.md`, `CONTRIBUTING.md # Enterprise-Ready Software Engineering Project +# pnpm +pnpm add @coinbase/onchaintestkit +``` -Welcome to the **Enterprise-Ready Software Engineering Project**. This repository is designed for professional development in Python, Java, and C++ with a focus on enterprise-grade solutions, scalability, and maintainability. +### Prerequisites + +- Node.js 14.0.0 or higher +- Playwright Test: `npm install --save-dev @playwright/test` + +## ๐ŸŽฏ Quick Start ---- +### 1. Prepare Wallet Extensions -## ๐Ÿš€ Business Focus +```bash +# Prepare MetaMask extension +npm run prepare-metamask -This project is tailored for **business enterprise-ready** solutions, ensuring professional-grade software engineering practices. It emphasizes: +# Or use the CLI directly +npx prepare-metamask +``` -- **Scalability**: Designed to handle enterprise-level workloads. -- **Maintainability**: Code structured for long-term use and collaboration. -- **Integration**: Seamless integration with existing enterprise systems. +### 2. Set Up Environment Variables ---- +```bash +export E2E_TEST_SEED_PHRASE="test test test test test test test test test test test junk" +``` -## ๐Ÿง‘โ€๐Ÿ’ป Your Role +โš ๏ธ **Warning**: Never use real seed phrases or funds for testing! -- **Role Type**: `{role_type}` expert in `{domain}` -- **Focus Area**: `{key_skill_area}` +### 3. Create Your First Test -As a contributor, your expertise in `{domain}` will help shape the success of this project. Focus on `{key_skill_area}` to ensure high-quality contributions. +```typescript +import { configure, createOnchainTest } from '@coinbase/onchaintestkit'; +import { test } from '@playwright/test'; ---- +const config = configure() + .withMetaMask() + .withSeedPhrase({ + seedPhrase: process.env.E2E_TEST_SEED_PHRASE, + password: 'TestPassword123' + }) + .build(); -## ๐Ÿ“œ Code Guidelines +test('connect wallet and interact', async () => { + const { page, wallet } = await createOnchainTest(config); + + await page.goto('https://your-dapp.com'); + await wallet.connect(); + + // Your test logic here +}); +``` -### General Guidelines +## ๐Ÿ”ง Configuration -- Use **language-specific conventions** for Python, Java, and C++. -- Follow **design patterns** and **best practices** for enterprise software. -- Optimize for **performance**, **readability**, and **scalability**. +### Basic Configuration -### Python +```typescript +import { configure } from '@coinbase/onchaintestkit'; -- Follow [PEP 8](https://peps.python.org/pep-0008/) for coding standards. -- Use type hints and docstrings for better readability. -- Write unit tests using `unittest` or `pytest`. +const config = configure() + .withMetaMask() + .withSeedPhrase({ + seedPhrase: process.env.E2E_TEST_SEED_PHRASE, + password: 'PASSWORD' + }) + .build(); +``` -### Java +### Fork Mode Testing -- Adhere to [Oracle's Java Code Conventions](https://www.oracle.com/java/technologies/javase/codeconventions-introduction.html). -- Use Maven or Gradle for dependency management. -- Write JUnit tests for all major components. +Test against a forked mainnet for reproducible tests: -### C++ +```typescript +const forkConfig = configure() + .withLocalNode({ + fork: 'https://eth-mainnet.g.alchemy.com/v2/your-api-key', + forkBlockNumber: 18500000, // Specific block for reproducibility + chainId: 1, + }) + .withMetaMask() + .withSeedPhrase({ + seedPhrase: process.env.E2E_TEST_SEED_PHRASE, + password: 'PASSWORD' + }) + .build(); +``` -- Follow [Google's C++ Style Guide](https://google.github.io/styleguide/cppguide.html). -- Use `CMake` for build configuration. -- Ensure memory safety and avoid undefined behavior. +### Multi-Network Support ---- +```typescript +import { baseSepolia } from 'viem/chains'; -## ๐Ÿ”ง Integration +const networkConfig = configure() + .withMetaMask() + .withSeedPhrase({ + seedPhrase: process.env.E2E_TEST_SEED_PHRASE, + password: 'PASSWORD' + }) + .withNetwork({ + name: baseSepolia.name, + rpcUrl: baseSepolia.rpcUrls.default.http[0], + chainId: baseSepolia.id, + symbol: baseSepolia.nativeCurrency.symbol, + }) + .build(); +``` -This project is designed to integrate seamlessly with enterprise systems. Key integration points include: +## ๐Ÿ” Supported Wallets -- **APIs**: RESTful APIs for communication between services. -- **Databases**: Support for relational and NoSQL databases. -- **CI/CD Pipelines**: Automated testing and deployment workflows. +OnChainTestKit provides native support for popular Web3 wallets: ---- +- **MetaMask** - Most widely used Ethereum wallet +- **Coinbase Wallet** - Coinbase's self-custody wallet +- **Phantom** - Leading Solana wallet with Ethereum support + +### Preparing Wallet Extensions + +```bash +# MetaMask +npm run prepare-metamask + +# Coinbase Wallet +npm run prepare-coinbase + +# Phantom +npm run prepare-phantom +``` + +## ๐Ÿ“š Documentation + +- [Full Documentation](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/tree/main/docs) +- [Installation Guide](./docs/installation.md) +- [User Guide](./docs/guide.md) +- [Examples](./example/) +- [API Reference](./docs/) + +## ๐Ÿงช Testing + +Run the test suite: + +```bash +npm test +``` + +## ๐Ÿค Contributing + +We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details. + +### Development Setup + +```bash +# Clone the repository +git clone https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit.git +cd https-github.com-joe10832-onchaintestkit + +# Install dependencies +npm install + +# Build the project +npm run build + +# Run tests +npm test + +# Format and lint +npm run format +npm run lint +``` + +## ๐Ÿ“„ License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## ๐Ÿ™ Acknowledgments + +Built by Coinbase and powered by Playwright for robust blockchain application testing. + +## ๐Ÿ”— Links + +- [GitHub Repository](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit) +- [npm Package](https://www.npmjs.com/package/@coinbase/onchaintestkit) +- [Issue Tracker](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues) -## ๐Ÿ“š Further Reading +## ๐Ÿ’ฌ Support -- [Python Best Practices](https://realpython.com/) -- [Java Design Patterns](https://java-design-patterns.com/) -- [C++ Modern Practices](https://isocpp.org/) +- ๐Ÿ“– [Documentation](./docs/) +- ๐Ÿ› [Report Issues](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues) +- ๐Ÿ’ก [Request Features](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues) --- -For questions or support, please open an issue or contact the project maintainer. \ No newline at end of file +**Note**: Always use test accounts and never use real funds when testing blockchain applications. From e07b8061e9b9e38bdec44594cbadeeee29973ba9 Mon Sep 17 00:00:00 2001 From: Roo Code Date: Tue, 23 Dec 2025 23:09:30 +0000 Subject: [PATCH 2/2] docs: polish and enhance documentation structure and clarity --- CONTRIBUTING.md | 465 ++++++++++++++++++++++++++++++++++-------------- README.md | 164 +++++++++++------ 2 files changed, 449 insertions(+), 180 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a0fe20..d0a2082 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,38 +1,58 @@ # Contributing to OnChainTestKit -Thank you for your interest in contributing to OnChainTestKit! We welcome contributions from the community. +Thank you for your interest in contributing to OnChainTestKit! We value contributions from the community and appreciate your time and effort. + +--- + +## Table of Contents + +- [Getting Started](#-getting-started) +- [Development Workflow](#-development-workflow) +- [Code Style Guidelines](#-code-style-guidelines) +- [Testing Guidelines](#-testing-guidelines) +- [Documentation](#-documentation) +- [Reporting Bugs](#-reporting-bugs) +- [Suggesting Features](#-suggesting-features) +- [Code Review Process](#-code-review-process) +- [Getting Help](#-getting-help) + +--- ## ๐Ÿš€ Getting Started ### Prerequisites -- Node.js 14.0.0 or higher -- npm, yarn, or pnpm -- Git -- Playwright Test +Before you begin, ensure you have the following installed: + +- **Node.js** 14.0.0 or higher +- **npm**, yarn, or pnpm +- **Git** +- **Playwright Test** + +### Development Environment Setup -### Setup Development Environment +Follow these steps to set up your local development environment: -1. **Fork and clone the repository** +#### 1. Fork and Clone ```bash git clone https://github.com/YOUR-USERNAME/https-github.com-joe10832-onchaintestkit.git cd https-github.com-joe10832-onchaintestkit ``` -2. **Install dependencies** +#### 2. Install Dependencies ```bash npm install ``` -3. **Build the project** +#### 3. Build the Project ```bash npm run build ``` -4. **Prepare wallet extensions** +#### 4. Prepare Wallet Extensions ```bash npm run prepare-metamask @@ -40,79 +60,99 @@ npm run prepare-coinbase npm run prepare-phantom ``` -5. **Set up environment variables** +#### 5. Configure Environment ```bash export E2E_TEST_SEED_PHRASE="test test test test test test test test test test test junk" ``` -โš ๏ธ **Never use real seed phrases or funds for testing!** +> โš ๏ธ **Security Warning**: Never use real seed phrases or funds for testing! -6. **Run tests** +#### 6. Verify Setup ```bash npm test ``` +--- + ## ๐Ÿ”„ Development Workflow ### 1. Create a Feature Branch -Always create a new branch for your changes: +Always work on a dedicated branch for your changes: ```bash -git checkout -b feature/your-feature-name -# or -git checkout -b fix/your-bug-fix +# For new features +git checkout -b feature/descriptive-feature-name + +# For bug fixes +git checkout -b fix/descriptive-bug-name + +# For documentation +git checkout -b docs/descriptive-doc-change ``` ### 2. Make Your Changes -- Write clean, maintainable code -- Follow the existing code style and patterns -- Add tests for new features or bug fixes -- Update documentation as needed +Follow these principles while making changes: + +- โœ… Write clean, maintainable code +- โœ… Follow existing code structure and patterns +- โœ… Add tests for new features or bug fixes +- โœ… Update documentation for API changes +- โœ… Keep commits atomic and focused ### 3. Test Your Changes +Run comprehensive checks before committing: + ```bash # Run all tests npm test -# Run linting +# Check code style npm run lint -# Fix linting issues +# Auto-fix linting issues npm run lint:fix # Format code npm run format + +# Build to verify compilation +npm run build ``` ### 4. Commit Your Changes -Use conventional commit messages: +We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: ```bash git add . -git commit -m "feat: add new wallet support" -# or -git commit -m "fix: resolve connection timeout issue" -# or -git commit -m "docs: update installation guide" +git commit -m "type: brief description of changes" ``` -#### Commit Message Format +**Commit Types:** -Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: +| Type | Description | Example | +|------|-------------|---------| +| `feat` | New feature | `feat: add support for Phantom wallet` | +| `fix` | Bug fix | `fix: resolve connection timeout issue` | +| `docs` | Documentation only | `docs: update installation guide` | +| `style` | Code style/formatting | `style: apply consistent indentation` | +| `refactor` | Code restructuring | `refactor: simplify config builder` | +| `test` | Test additions/changes | `test: add wallet integration tests` | +| `chore` | Maintenance tasks | `chore: update dependencies` | +| `perf` | Performance improvement | `perf: optimize wallet loading` | -- `feat:` - New feature -- `fix:` - Bug fix -- `docs:` - Documentation changes -- `style:` - Code style changes (formatting, etc.) -- `refactor:` - Code refactoring -- `test:` - Test changes -- `chore:` - Maintenance tasks +**Example Commits:** + +```bash +git commit -m "feat: add multi-chain support for Base network" +git commit -m "fix: resolve MetaMask extension loading error" +git commit -m "docs: add fork mode configuration examples" +``` ### 5. Push to Your Fork @@ -120,176 +160,343 @@ Follow the [Conventional Commits](https://www.conventionalcommits.org/) specific git push origin feature/your-feature-name ``` -### 6. Create a Pull Request +### 6. Submit a Pull Request -1. Go to the [repository](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit) -2. Click "New Pull Request" -3. Select your branch -4. Fill in the PR template with details about your changes -5. Submit the pull request +1. Navigate to the [repository](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit) +2. Click **"New Pull Request"** +3. Select your feature branch +4. Fill out the PR template completely +5. Link any related issues +6. Submit for review + +--- ## ๐Ÿ“ Code Style Guidelines -### TypeScript/JavaScript +### TypeScript/JavaScript Standards + +**Code Organization:** + +```typescript +// 1. External imports first +import { test, expect } from '@playwright/test'; + +// 2. Internal imports second +import { configure, createOnchainTest } from '@coinbase/onchaintestkit'; -- Use TypeScript for all new code -- Follow the existing code structure and patterns -- Use meaningful variable and function names -- Add JSDoc comments for public APIs -- Keep functions small and focused -- Avoid unnecessary complexity +// 3. Type definitions +interface WalletConfig { + seedPhrase: string; + password: string; +} -### Code Quality +// 4. Implementation +export function setupWallet(config: WalletConfig) { + // Implementation +} +``` -- **Write tests**: All new features should include tests -- **Type safety**: Leverage TypeScript's type system -- **Error handling**: Handle errors appropriately -- **Documentation**: Update docs for API changes -- **Performance**: Consider performance implications +**Best Practices:** -### File Organization +- โœ… Use TypeScript for all new code +- โœ… Leverage TypeScript's type system fully +- โœ… Use meaningful, descriptive names +- โœ… Add JSDoc comments for public APIs +- โœ… Keep functions small and focused (< 50 lines) +- โœ… Prefer pure functions when possible +- โœ… Handle errors explicitly + +**Example:** + +```typescript +/** + * Configures a wallet for testing + * @param seedPhrase - Test wallet seed phrase + * @param password - Wallet password + * @returns Configured wallet instance + * @throws {Error} If seed phrase is invalid + */ +export function configureWallet( + seedPhrase: string, + password: string +): WalletInstance { + if (!seedPhrase || seedPhrase.split(' ').length !== 12) { + throw new Error('Invalid seed phrase: must be 12 words'); + } + + return new WalletInstance({ seedPhrase, password }); +} +``` + +### Code Quality Checklist + +- โ˜‘๏ธ **Type Safety** - No `any` types without justification +- โ˜‘๏ธ **Error Handling** - All errors handled appropriately +- โ˜‘๏ธ **Documentation** - Public APIs have JSDoc comments +- โ˜‘๏ธ **Testing** - New code includes tests +- โ˜‘๏ธ **Performance** - No obvious performance issues + +### Project Structure ``` src/ -โ”œโ”€โ”€ cli/ # CLI tools and scripts -โ”œโ”€โ”€ contracts/ # Smart contract management -โ”œโ”€โ”€ node/ # Local node and network interceptor -โ”œโ”€โ”€ utils/ # Utility functions -โ”œโ”€โ”€ wallets/ # Wallet implementations +โ”œโ”€โ”€ cli/ # CLI tools and commands +โ”‚ โ”œโ”€โ”€ prepare-coinbase.mjs +โ”‚ โ”œโ”€โ”€ prepare-metamask.mjs +โ”‚ โ””โ”€โ”€ prepare-phantom.mjs +โ”œโ”€โ”€ contracts/ # Smart contract utilities +โ”‚ โ””โ”€โ”€ SmartContractManager.ts +โ”œโ”€โ”€ node/ # Local node management +โ”‚ โ”œโ”€โ”€ LocalNodeManager.ts +โ”‚ โ”œโ”€โ”€ NetworkInterceptor.ts +โ”‚ โ””โ”€โ”€ types.ts +โ”œโ”€โ”€ utils/ # Shared utilities +โ”‚ โ””โ”€โ”€ ConnectorUtil.ts +โ”œโ”€โ”€ wallets/ # Wallet implementations โ”‚ โ”œโ”€โ”€ BaseWallet.ts +โ”‚ โ”œโ”€โ”€ types.ts โ”‚ โ”œโ”€โ”€ Coinbase/ โ”‚ โ”œโ”€โ”€ MetaMask/ โ”‚ โ””โ”€โ”€ Phantom/ -โ””โ”€โ”€ index.ts # Main exports +โ”œโ”€โ”€ configBuilder.ts # Configuration builder +โ”œโ”€โ”€ constants.ts # Shared constants +โ”œโ”€โ”€ createOnchainTest.ts # Test creation +โ”œโ”€โ”€ index.ts # Public API exports +โ””โ”€โ”€ types.ts # Shared types ``` +--- + ## ๐Ÿงช Testing Guidelines ### Writing Tests +**Test Organization:** + - Place tests in the `tests/` directory -- Mirror the `src/` structure -- Use descriptive test names -- Test edge cases and error conditions -- Keep tests independent and isolated +- Mirror the `src/` directory structure +- Use descriptive test file names (`*.test.ts` or `*.spec.ts`) -### Test Structure +**Test Structure:** ```typescript import { test, expect } from '@playwright/test'; import { configure, createOnchainTest } from '@coinbase/onchaintestkit'; -test.describe('Feature Name', () => { - test('should do something specific', async () => { - // Arrange +test.describe('Wallet Connection', () => { + test('should connect MetaMask wallet successfully', async () => { + // Arrange - Set up test conditions const config = configure() .withMetaMask() + .withSeedPhrase({ + seedPhrase: process.env.E2E_TEST_SEED_PHRASE!, + password: 'TestPassword123' + }) .build(); - // Act - const result = await someFunction(); + // Act - Perform the action + const { page, wallet } = await createOnchainTest(config); + await page.goto('https://test-dapp.com'); + await wallet.connect(); - // Assert - expect(result).toBe(expected); + // Assert - Verify the outcome + expect(await wallet.isConnected()).toBe(true); + }); + + test('should handle connection rejection gracefully', async () => { + // Test error scenarios }); }); ``` +**Testing Best Practices:** + +- โœ… Test one thing per test +- โœ… Use descriptive test names +- โœ… Test both success and failure paths +- โœ… Keep tests independent and isolated +- โœ… Clean up resources after tests +- โœ… Use meaningful assertions + +--- + ## ๐Ÿ“š Documentation -### Updating Documentation +### When to Update Documentation + +Update documentation when you: -When making changes, update relevant documentation: +- Add new features or APIs +- Change existing behavior +- Fix bugs that affect usage +- Add new configuration options -- **README.md** - Main project overview -- **docs/** - Detailed guides and API reference -- **Code comments** - Inline documentation -- **Examples** - Usage examples in `example/` +### Documentation Files + +| File | Purpose | +|------|---------| +| `README.md` | Project overview and quick start | +| `CONTRIBUTING.md` | Contribution guidelines (this file) | +| `docs/` | Detailed guides and API reference | +| `example/` | Working code examples | +| JSDoc comments | Inline API documentation | ### Documentation Style -- Be clear and concise -- Include code examples -- Explain the "why" not just the "what" -- Keep examples up to date -- Use proper markdown formatting +**Writing Guidelines:** + +- โœ… Be clear and concise +- โœ… Include code examples +- โœ… Explain the "why" behind decisions +- โœ… Keep examples up to date +- โœ… Use proper markdown formatting +- โœ… Add links to related documentation + +**Example:** + +```markdown +## Configuring Fork Mode + +Fork mode allows you to test against a snapshot of mainnet at a specific block: + +\```typescript +const config = configure() + .withLocalNode({ + fork: 'https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY', + forkBlockNumber: 18500000 // Pin to specific block + }) + .build(); +\``` + +This ensures reproducible tests by using a consistent blockchain state. +``` + +--- ## ๐Ÿ› Reporting Bugs -### Before Submitting +### Before Submitting a Bug Report -1. Check existing issues to avoid duplicates -2. Test with the latest version -3. Verify it's not a configuration issue +1. โœ… **Search existing issues** - Check if it's already reported +2. โœ… **Test with latest version** - Verify bug exists in current release +3. โœ… **Verify configuration** - Ensure your setup is correct +4. โœ… **Create minimal reproduction** - Isolate the issue ### Bug Report Template -Include: +Include the following information: -- **Description**: Clear description of the bug -- **Steps to Reproduce**: Detailed steps to reproduce -- **Expected Behavior**: What should happen -- **Actual Behavior**: What actually happens -- **Environment**: OS, Node version, package version -- **Code Sample**: Minimal reproducible example +**Description** +Clear and concise description of the bug. + +**Steps to Reproduce** +1. Configure wallet with... +2. Run test with... +3. Observe error... + +**Expected Behavior** +What should happen? + +**Actual Behavior** +What actually happens? + +**Environment** +- OS: [e.g., macOS 13.0, Ubuntu 22.04] +- Node version: [e.g., v18.16.0] +- Package version: [e.g., 1.2.0] +- Wallet: [e.g., MetaMask 11.0.0] + +**Code Sample** +```typescript +// Minimal reproducible example +``` + +**Additional Context** +Screenshots, error messages, or other relevant information. + +--- ## ๐Ÿ’ก Suggesting Features -We welcome feature suggestions! Please: +We welcome feature suggestions! To propose a new feature: -1. Check if the feature already exists or is planned -2. Open an issue with the `enhancement` label -3. Describe the use case and benefits -4. Provide examples of how it would work +1. โœ… **Check existing issues** - See if it's already suggested +2. โœ… **Open an issue** - Use the `enhancement` label +3. โœ… **Describe the use case** - Explain the problem it solves +4. โœ… **Provide examples** - Show how it would work +5. โœ… **Consider alternatives** - Discuss other approaches + +--- ## ๐Ÿ” Code Review Process -### What We Look For +### Review Criteria + +Reviewers evaluate submissions based on: -- **Correctness**: Does it work as intended? -- **Tests**: Are there adequate tests? -- **Documentation**: Is it well documented? -- **Style**: Does it follow our guidelines? -- **Performance**: Are there performance implications? -- **Security**: Are there security concerns? +| Aspect | What We Check | +|--------|---------------| +| **Correctness** | Does it work as intended? No bugs? | +| **Tests** | Are there adequate tests? Do they pass? | +| **Documentation** | Is it well documented? | +| **Style** | Does it follow our guidelines? | +| **Performance** | Are there performance implications? | +| **Security** | Are there security concerns? | +| **Breaking Changes** | Is backward compatibility maintained? | ### Review Timeline -- Initial review: Within 1-3 business days -- Feedback incorporated: Review continues -- Approved: Ready to merge +- **Initial Review**: Within 1-3 business days +- **Feedback**: Maintainers provide constructive feedback +- **Iteration**: Make requested changes +- **Approval**: Once approved, PR will be merged + +--- ## ๐Ÿšซ What NOT to Contribute Please avoid: -- โŒ Breaking changes without discussion -- โŒ Large refactors without prior approval -- โŒ Code that fails tests or linting -- โŒ Unrelated changes in a single PR -- โŒ Commits with real secrets or credentials +- โŒ **Breaking changes** without prior discussion +- โŒ **Large refactors** without approval +- โŒ **Failing tests** or linting errors +- โŒ **Unrelated changes** in a single PR +- โŒ **Real credentials** or secrets in code +- โŒ **Dependencies** without justification + +--- ## ๐Ÿ“ž Getting Help -Need help with your contribution? +Need assistance with your contribution? -- ๐Ÿ’ฌ Open a [discussion](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/discussions) -- ๐Ÿ“ง Ask questions in your PR -- ๐Ÿ“– Check the [documentation](./docs/) -- ๐Ÿ› Open an [issue](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues) +- ๐Ÿ’ฌ **[Discussions](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/discussions)** - Ask questions and share ideas +- ๐Ÿ“ง **PR Comments** - Ask questions directly in your pull request +- ๐Ÿ“– **[Documentation](./docs/)** - Check the comprehensive guides +- ๐Ÿ› **[Issues](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues)** - Report problems or request features + +--- ## ๐ŸŽ‰ Recognition -Contributors will be: +Contributors are valued members of our community: -- Listed in the project's contributors -- Credited in release notes (for significant contributions) -- Part of a growing community of blockchain testing enthusiasts +- โœจ Listed in project contributors +- ๐Ÿ“ Credited in release notes (for significant contributions) +- ๐ŸŒŸ Part of our blockchain testing community + +--- ## ๐Ÿ“„ License -By contributing, you agree that your contributions will be licensed under the MIT License. +By contributing to OnChainTestKit, you agree that your contributions will be licensed under the MIT License. --- -Thank you for contributing to OnChainTestKit! Every contribution, no matter how small, helps make blockchain testing better for everyone. ๐Ÿš€ +
+ +**Thank you for contributing to OnChainTestKit!** + +Every contribution, no matter the size, helps make blockchain testing better for everyone. ๐Ÿš€ + +
diff --git a/README.md b/README.md index 4675c4a..bf940b1 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,33 @@ [![npm version](https://img.shields.io/npm/v/@coinbase/onchaintestkit.svg)](https://www.npmjs.com/package/@coinbase/onchaintestkit) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -**OnChainTestKit** is an end-to-end testing toolkit for blockchain applications, powered by Playwright. It provides comprehensive testing utilities for Web3 applications with native wallet support. +End-to-end testing toolkit for blockchain applications, powered by Playwright. + +--- + +## Table of Contents + +- [Features](#-features) +- [Installation](#-installation) +- [Quick Start](#-quick-start) +- [Configuration](#-configuration) +- [Supported Wallets](#-supported-wallets) +- [Documentation](#-documentation) +- [Contributing](#-contributing) +- [License](#-license) + +--- ## ๐Ÿš€ Features -- ๐Ÿ”— **Blockchain Testing**: Complete E2E testing for blockchain applications -- ๐ŸŽญ **Playwright Integration**: Built on Playwright for reliable automation -- ๐Ÿ” **Multiple Wallets**: Native support for MetaMask, Coinbase Wallet, and Phantom -- ๐ŸŒ **Network Support**: Test on mainnet, testnets, or local nodes with fork mode -- ๐Ÿ› ๏ธ **Easy Configuration**: Simple, chainable configuration API -- ๐Ÿ“ **TypeScript Support**: Full TypeScript definitions included +- **๐Ÿ”— Blockchain Testing** - Comprehensive E2E testing for Web3 applications +- **๐ŸŽญ Playwright Powered** - Built on Playwright for reliable, fast automation +- **๐Ÿ” Multi-Wallet Support** - Native integration with MetaMask, Coinbase Wallet, and Phantom +- **๐ŸŒ Network Flexibility** - Test on mainnet, testnets, or forked local nodes +- **๐Ÿ› ๏ธ Simple Configuration** - Intuitive, chainable API for easy setup +- **๐Ÿ“ TypeScript First** - Full type definitions for enhanced developer experience + +--- ## ๐Ÿ“ฆ Installation @@ -31,35 +48,43 @@ pnpm add @coinbase/onchaintestkit ### Prerequisites -- Node.js 14.0.0 or higher -- Playwright Test: `npm install --save-dev @playwright/test` +- **Node.js** 14.0.0 or higher +- **Playwright Test**: Install as dev dependency + ```bash + npm install --save-dev @playwright/test + ``` + +--- ## ๐ŸŽฏ Quick Start -### 1. Prepare Wallet Extensions +### Step 1: Prepare Wallet Extensions ```bash # Prepare MetaMask extension npm run prepare-metamask -# Or use the CLI directly +# Alternatively, use npx npx prepare-metamask ``` -### 2. Set Up Environment Variables +### Step 2: Configure Environment + +Set up your test environment variables: ```bash export E2E_TEST_SEED_PHRASE="test test test test test test test test test test test junk" ``` -โš ๏ธ **Warning**: Never use real seed phrases or funds for testing! +> โš ๏ธ **Security Warning**: Only use test seed phrases. Never use real wallet credentials or funds. -### 3. Create Your First Test +### Step 3: Write Your First Test ```typescript import { configure, createOnchainTest } from '@coinbase/onchaintestkit'; import { test } from '@playwright/test'; +// Configure test environment const config = configure() .withMetaMask() .withSeedPhrase({ @@ -68,20 +93,28 @@ const config = configure() }) .build(); -test('connect wallet and interact', async () => { +// Write your test +test('should connect wallet and interact with dApp', async () => { const { page, wallet } = await createOnchainTest(config); + // Navigate to your dApp await page.goto('https://your-dapp.com'); + + // Connect wallet await wallet.connect(); - // Your test logic here + // Add your test logic here }); ``` +--- + ## ๐Ÿ”ง Configuration ### Basic Configuration +Simple wallet configuration for testing: + ```typescript import { configure } from '@coinbase/onchaintestkit'; @@ -96,13 +129,13 @@ const config = configure() ### Fork Mode Testing -Test against a forked mainnet for reproducible tests: +Test against a forked version of mainnet for deterministic, reproducible tests: ```typescript const forkConfig = configure() .withLocalNode({ fork: 'https://eth-mainnet.g.alchemy.com/v2/your-api-key', - forkBlockNumber: 18500000, // Specific block for reproducibility + forkBlockNumber: 18500000, // Pin to specific block for consistency chainId: 1, }) .withMetaMask() @@ -113,7 +146,9 @@ const forkConfig = configure() .build(); ``` -### Multi-Network Support +### Multi-Network Configuration + +Configure custom networks for comprehensive testing: ```typescript import { baseSepolia } from 'viem/chains'; @@ -133,88 +168,115 @@ const networkConfig = configure() .build(); ``` +--- + ## ๐Ÿ” Supported Wallets -OnChainTestKit provides native support for popular Web3 wallets: +OnChainTestKit provides first-class support for the most popular Web3 wallets: -- **MetaMask** - Most widely used Ethereum wallet -- **Coinbase Wallet** - Coinbase's self-custody wallet -- **Phantom** - Leading Solana wallet with Ethereum support +| Wallet | Description | Command | +|--------|-------------|---------| +| **MetaMask** | Most widely used Ethereum wallet | `npm run prepare-metamask` | +| **Coinbase Wallet** | Coinbase's self-custody solution | `npm run prepare-coinbase` | +| **Phantom** | Leading Solana wallet with Ethereum support | `npm run prepare-phantom` | ### Preparing Wallet Extensions ```bash -# MetaMask -npm run prepare-metamask +# Prepare all wallets at once +npm run prepare-metamask && npm run prepare-coinbase && npm run prepare-phantom -# Coinbase Wallet +# Or prepare individually as needed +npm run prepare-metamask npm run prepare-coinbase - -# Phantom npm run prepare-phantom ``` +--- + ## ๐Ÿ“š Documentation -- [Full Documentation](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/tree/main/docs) -- [Installation Guide](./docs/installation.md) -- [User Guide](./docs/guide.md) -- [Examples](./example/) -- [API Reference](./docs/) +Explore comprehensive guides and resources: + +- **[Installation Guide](./docs/installation.md)** - Detailed setup instructions +- **[User Guide](./docs/guide.md)** - Complete usage documentation +- **[Examples](./example/)** - Working code examples +- **[API Reference](./docs/)** - Full API documentation + +--- ## ๐Ÿงช Testing -Run the test suite: +Run the complete test suite: ```bash npm test ``` +--- + ## ๐Ÿค Contributing -We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details. +We welcome contributions from the community! See our [Contributing Guide](./CONTRIBUTING.md) for details on: + +- Setting up your development environment +- Code style guidelines +- Submitting pull requests +- Reporting bugs and requesting features -### Development Setup +### Quick Development Setup ```bash -# Clone the repository +# Clone and navigate to repository git clone https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit.git cd https-github.com-joe10832-onchaintestkit -# Install dependencies +# Install dependencies and build npm install - -# Build the project npm run build # Run tests npm test -# Format and lint +# Code quality checks npm run format npm run lint ``` +--- + ## ๐Ÿ“„ License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. + +--- ## ๐Ÿ™ Acknowledgments -Built by Coinbase and powered by Playwright for robust blockchain application testing. +Built with โค๏ธ by Coinbase and powered by Playwright for robust blockchain testing. + +--- + +## ๐Ÿ”— Resources -## ๐Ÿ”— Links +- **[GitHub Repository](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit)** - Source code and development +- **[npm Package](https://www.npmjs.com/package/@coinbase/onchaintestkit)** - Package registry +- **[Issue Tracker](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues)** - Bug reports and feature requests -- [GitHub Repository](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit) -- [npm Package](https://www.npmjs.com/package/@coinbase/onchaintestkit) -- [Issue Tracker](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues) +--- ## ๐Ÿ’ฌ Support -- ๐Ÿ“– [Documentation](./docs/) -- ๐Ÿ› [Report Issues](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues) -- ๐Ÿ’ก [Request Features](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues) +Need help? We're here for you: + +- ๐Ÿ“– **[Documentation](./docs/)** - Comprehensive guides and tutorials +- ๐Ÿ› **[Report Issues](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues)** - Found a bug? Let us know +- ๐Ÿ’ก **[Request Features](https://github.com/MunyayLLC/https-github.com-joe10832-onchaintestkit/issues)** - Have an idea? Share it with us --- -**Note**: Always use test accounts and never use real funds when testing blockchain applications. +
+ +**โš ๏ธ Important**: Always use test accounts and never use real funds when testing blockchain applications. + +