Skip to content

for-devs.md

Latest commit

 

History

History
153 lines (102 loc) · 3.89 KB

for-devs.md

File metadata and controls

153 lines (102 loc) · 3.89 KB

Developer Information

This file is intended for developers. It provides details on the project's structure and instructions on how to work with it.

1. Packages

Common:

  • types - Declarations of interfaces and constants, used in different packages.

Client-side (browser):

  • procaptcha-bundle - Displaying captcha widget

    • procaptcha-frictionless (Dynamic CAPTCHA that does client-side detection to determine whether to serve PoW/Image)
    • procaptcha-react (image)
    • procaptcha-pow (Proof-of-Work)

  • widget-skeleton - Widget skeleton wrapped into the web component

Server-side (node.js):

  • provider - API Endpoints for the captcha widget
    • cli - CLI wrapper for the provider, that starts Express
  • database - Mongo DB Query builder
    • types-database - declaration of interfaces and types used in the Query builder

Building configs (for Vite):

dev/config/src/vite:

  • vite.frontend.config.ts
  • vite.backend.config.ts

2. Code Quality & Style

  • ESLint - static code analyses
  • Biome - formatting (see /biome.json)

If your IDE supports biome (directly, or via plugin), you can configure it to work with the /biome.json).

3. Names in code

  • dapp, dappAccount = clientId = siteKey in the portal
  • user, userAccount = userId

3. Commands

  • Installation: npm install
  • Building packages: npm run build:all
  • Building the bundle: npm run build:bundle
  • Lint checks: npm run lint
  • Lint formatting fixes: npm run lint-fix

4. Local setup

4.1) Environment Setup

This step should be done only once, after the repository has been cloned, then this step should be omitted.

To set up the environment for testing, run the following commands:

cp demos/client-example-server/env.development demos/client-example-server/.env.test
cp demos/client-bundle-example/env.development demos/client-bundle-example/.env.test
cp dev/scripts/env.test .env.test
cp dev/scripts/env.test dev/scripts/.env.test
cp dev/scripts/env.test packages/cli/.env.test
cp dev/scripts/env.test packages/procaptcha-bundle/.env.test

4.2) Launching DB service

The DB is necessary for all kind of the tests. Since the DB is docked, to start the DB service run the following:

docker compose --file ./docker/docker-compose.test.yml up -d --remove-orphans --force-recreate --always-recreate-deps

Note: After the testing is done, stop it using the down command:

docker compose --file ./docker/docker-compose.test.yml down

4.3) DB population

This command should be called once per the container lifetime, and adds the initial data, like domains, siteKeys, etc.

NODE_ENV="test" npm run setup

5. Local tests

5.1) Unit tests

Launch services:

NODE_ENV=test npm run start:provider:admin
  • Provider:admin service is required for the provider unit tests.

Run all the unit tests:

npm run test
  • The command will loop through all the package/* folders, and run individual unit tests for each package.

Tip: You can also run package-related unit tests individually, by running npm run test inside the target package folder.

5.2) E2E Bundle Tests

Launch services:

npm run -w @prosopo/client-example-server build ; NODE_ENV=test npm run start:server
NODE_ENV=test npm run start:provider:admin
NODE_ENV="development" npm -w @prosopo/procaptcha-bundle run bundle
NODE_ENV=test npm run start:bundle

Run tests:

NODE_ENV=test npm -w @prosopo/cypress-shared run cypress:open:client-bundle-example

6. Local playground (demo)

# demo
npm run start:bundle

# server (if you need verification)
NODE_ENV=test npm run start:provider:admin

# bundle
turbo run build --filter @prosopo/procaptcha-bundle...; 
NODE_ENV=development npm -w @prosopo/procaptcha-bundle run bundle; 
npm -w @prosopo/procaptcha-bundle run serve

# visit
http://localhost:9232/pow-explicit.html