Neuron CKB Wallet

To ensure tests are repeatable and independent, follow these data management principles:

• User Data Isolation: Each test run isolates Electron user data by setting XDG_CONFIG_HOME under the Playwright test output directory. Do not rely on a developer's local Neuron profile.
• State Setup: For tests requiring specific wallet, chain, or RPC states, use the explicit setup helpers located in e2e/fixtures. Avoid using manually prepared local data to ensure consistency in CI.

To enable log encryption in Neuron, you must generate an RSA keypair. The private key is used for decryption, and the public key is used to encrypt logs via the LOG_ENCRYPTION_PUBLIC_KEY environment variable.

Use the following OpenSSL commands to generate the keys:

1. Generate the ADMIN_PRIVATE_KEY (RSA private key).
2. Generate the LOG_ENCRYPTION_PUBLIC_KEY (RSA public key) from the private key.

# for ADMIN_PRIVATE_KEY
openssl genrsa -out key.pem 2048

# for LOG_ENCRYPTION_PUBLIC_KEY
openssl rsa -in key.pem -outform PEM -pubout -out public.pem

To run Neuron in development mode, first download the CKB binary for your platform, then start the application. This will launch both neuron-ui (the React UI layer) and neuron-wallet (the core wallet layer).

$ ./scripts/download-ckb.sh
$ yarn start

Note: As of v0.26.0, Neuron automatically bundles and starts a CKB binary for Mainnet. If you prefer to use your own local CKB node, ensure it is running before launching Neuron.

To build and run Neuron from the source code, ensure you have node >= 18.12.0 and yarn >= 1.14 installed. This project uses lerna for package management.

1. Install lerna globally: yarn global add lerna
2. Install and link dependencies: yarn lerna run rebuild:nativemodules
3. Add the CKB Indexer binary to the appropriate platform directory in packages/neuron-wallet/bin/{win/linux/mac}/.

$ yarn global add lerna
$ yarn
$ lerna run rebuild:nativemodules

Because Playwright launches an Electron app window, a plain headless Node environment is insufficient. On Linux CI environments, you must run the tests under Xvfb to provide a virtual graphical session.

Use the following command to run tests with a virtual screen of 1280x960:

xvfb-run --auto-servernum --server-args="-screen 0 1280x960x24" yarn test:e2e

In development mode, you can run the UI and the wallet core as separate processes.

To start the React UI layer at http://localhost:3000: yarn start:ui

To start the core wallet layer: yarn start:wallet

# start neuron-ui at `http://localhost:3000`
$ yarn start:ui

# start neuron-wallet
$ yarn start:wallet

The Neuron Playwright E2E harness is used for release-regression testing of the Electron wallet. To run the tests, ensure you have installed dependencies first.

Standard execution: Runs tests in headless mode.

Useful variants:

• yarn test:e2e:headed: Runs tests with a visible browser/app window.
• yarn test:e2e:ui: Opens the Playwright UI mode for interactive debugging.

Note on execution environment: The test configuration automatically starts the Vite UI server at http://127.0.0.1:3000. It then launches the Electron main process from packages/neuron-wallet (this requires yarn build:main to have been executed previously to compile the main process).

yarn install
yarn test:e2e

When writing or maintaining E2E tests, follow these selector best practices to ensure stability:

1. Prefer stable locators: Use user-facing locators such as getByRole, getByText, or labels whenever possible.
2. Avoid fragile selectors: Do not depend on generated class names or translated text/copy, as these change frequently.
3. Use data-testid: If a flow requires precision that standard locators cannot provide, add explicit data-testid attributes to the components in the source code.

The Navbar automatically monitors and displays warning alerts for the following conditions:

1. Missing Indexer: If the external CKB node is detected without an indexer (verifyCkbResult.withIndexer is false).
2. Incompatible CKB Node: If the CKB node version is incompatible with the current Neuron version.
3. Neuron Update Required: If a new version of Neuron is available and the connected CKB node requires an update to remain compatible.

These alerts are triggered using showGlobalAlertDialog and provide actionable buttons (e.g., a 'learn more' link that redirects to the download page).

To develop using Devnet instead of Testnet, modify the packages/neuron-wallet/.env file. Replace the testnet script entries with the corresponding dev script entries.

Environment variable keys follow a pattern constructed from the network, script name, and field name (e.g., TESTNET_SUDT_DEP_TXHASH).