README (6200B)
1 # GNU Taler Wallet & Anastasis Web UI 2 3 This repository contains the implementation of a wallet for GNU Taler written 4 in TypeScript and Anastasis Web UI 5 6 ## Dependencies 7 8 The following dependencies are required to build the wallet: 9 10 - python>=3.8 11 - nodejs>=20 12 - jq 13 - npm 14 - pnpm>=11.1.2 15 - zip 16 17 Note that you can install pnpm as an unprivileged user by running 18 19 ```shell 20 npm config set prefix $HOME/.npm-global 21 export PATH=$HOME.npm-global/bin:$PATH 22 npm install -g pnpm 23 ``` 24 25 ## Preparing the repository 26 27 After running clone you should bootstrap the repository. 28 29 ```shell 30 ./bootstrap 31 ``` 32 33 ## Installation 34 35 The CLI version of the wallet supports the normal GNU installation process. 36 37 ```shell 38 ./bootstrap 39 ./configure [ --prefix=$PREFIX ] && make install 40 ``` 41 42 ### Compiling from Git 43 44 If you are compiling the code from git, you have to run `./bootstrap` before 45 running `./configure`. 46 47 ## Pushing a new prebuilt version 48 49 After compiling run 50 51 ```shell 52 make prebuilt 53 ``` 54 55 This will create a directory `prebuilt` with a git subtree, 56 build every prebuilt project, copy everything into this subtree 57 and create a commit with the default message mentioning from 58 which revision the prebuilt was created. 59 When the script completes the prebuilt version can should 60 be manually pushed. 61 62 ```shell 63 cd prebuilt 64 git push 65 ``` 66 67 ### Building the WebExtension 68 69 The WebExtension can be built via the 'webextension' make target: 70 71 ```shell 72 ./configure && make webextension 73 ``` 74 75 This creates the browser-specific WebExtension ZIP files in 76 77 ``` 78 packages/wallet-webui/dist/extension/ 79 ``` 80 81 The Chrome and Firefox archives are named 82 `taler-wallet-<browser>-<version>.zip`. The corresponding unpacked builds are 83 in the `chrome/` and `firefox/` subdirectories. 84 85 ### Installing local WebExtension 86 87 Firefox: 88 - Settings 89 - Add-ons 90 - Manage your extension -> Debug Add-ons 91 - Load temporary Add-on... 92 - Select the Firefox zip under `packages/wallet-webui/dist/extension/` 93 94 Chrome: 95 - Settings 96 - More tools 97 - Extensions 98 - Load unpacked 99 - Select `packages/wallet-webui/dist/extension/chrome/` 100 101 ### Reviewing WebExtension UI examples 102 103 The wallet UI includes a searchable story catalogue. To run the development 104 server use: 105 106 ```shell 107 make webextension-dev 108 ``` 109 110 Open the Storybook route from the running wallet to review the registered 111 fixtures in `packages/wallet-webui/src/stories/`. 112 113 ### WebExtension UI Components 114 115 Every group of component have a directory and a README. 116 Testing component is based in two main category: 117 118 - UI testing 119 - State transition testing 120 121 For UI testing, every story example will be taken as a unit test. 122 For State testing, every stateful component should have an `useStateComponent` function that will be tested in a \*.test.ts file. 123 124 ### Testing WebExtension 125 126 After building the WebExtension, use the browser-specific output under 127 `packages/wallet-webui/dist/extension/`. 128 129 Firefox users: 130 131 - Go to about:addons 132 - Then `debug addon` (or about:debugging#/runtime/this-firefox) 133 - Then `Load temporary addon...` 134 - Select the `taler-wallet-firefox-*.zip` 135 136 Chrome users: 137 138 - Settings -> More tools -> Extensions (or go to chrome://extensions/) 139 - `Load unpacked` button in the upper left 140 - Select `packages/wallet-webui/dist/extension/chrome/` 141 142 ## Unit and package tests 143 144 Run the repository check from a clean set of generated files with: 145 146 ```shell 147 make check 148 ``` 149 150 The command builds the workspace, runs every package test command, continues 151 after package failures, and prints one summary at the end. To rerun only one 152 package while working, use its workspace name, for example: 153 154 ```shell 155 pnpm --filter @gnu-taler/taler-wallet-core test 156 ``` 157 158 Package test commands are responsible for removing their own generated test 159 output, so direct package runs cannot pick up JavaScript left behind by an 160 older source tree. See the [test runner design](doc/testrunner.md) for the 161 output, isolation, and generated-file conventions. 162 163 # Integration Tests 164 165 This repository comes with integration tests for GNU Taler. To run them, 166 install the wallet first. Then use the test runner from the 167 taler-integrationtests package: 168 169 ```shell 170 # List available tests 171 taler-wallet-cli testing list-integrationtests 172 173 # Run all tests 174 taler-wallet-cli testing run-integrationtests 175 176 # Run all tests matching pattern 177 taler-wallet-cli testing run-integrationtests $GLOB 178 179 $ Run all tests from a suite 180 taler-wallet-cli testing run-integrationtests --suites=wallet 181 ``` 182 183 The test runner accepts a bash glob pattern as parameter. Individual tests can 184 be run by specifying their name. 185 186 To check coverage, use c8 from the root of the repository and make sure that the taler-wallet-cli 187 from the source tree is executed, and not the globally installed one: 188 189 ``` 190 c8 ./packages/taler-wallet-cli/bin/taler-wallet-cli '*' 191 ``` 192 193 ## Minimum required browser for WebEx 194 195 The extension manifests, including Firefox's minimum supported version, are 196 generated by `packages/wallet-webui/manifest.mjs`. 197 198 ## Anastasis Web UI 199 200 ## Building for deploy 201 202 To build the Anastasis SPA run: 203 204 ```shell 205 make anastasis-webui 206 ``` 207 208 It will run the test suite and put everything into the dist folder under the project root (packages/anastasis-webui). 209 You can copy the SPA directly to work local webserver. 210 211 ```shell 212 cp -Tr ./packages/anastasis-webui/dist/prod /var/www/html/anastasis 213 ``` 214 215 Additionally you can create a zip file with the content to upload into a web server: 216 217 ```shell 218 make anastasis-webui-dist 219 ``` 220 221 It creates the zip file named `anastasis-webui.zip` 222 223 ## Building explored release in a container 224 225 First create a container with a base image, copy the release tar file and get inside the virtual machine. 226 227 ```shell 228 podman pull ubuntu:24.04 229 podman container create --name builder ubuntu:24.04 sleep infinity 230 podman container start builder 231 podman container cp taler-wallet-v*.tar.gz builder:/root/ 232 podman exec -it -w /root builder /bin/bash 233 ``` 234 235 Then inside the vm make sure you have the required software and follow the instruction for building. 236 237 Installing requirements 238 239 ```shell 240 apt update && apt install -y nodejs curl vim less python3 make zip jq npm 241 npm install --global corepack 242 tar xzf taler-wallet-v*.tar.gz 243 cd taler-wallet-v*/ 244 corepack enable pnpm 245 pnpm --version 246 ```