@o1js/testing #2093

boray · 2025-03-24T08:51:35Z

This pull request introduces a new package @o1js/testing and includes several changes to support this addition. The changes involve setting up the package structure, configuration files, and exporting necessary utilities.

New Package Setup:

src/testing/package.json: Created a new package.json file to define the @o1js/testing package, including scripts for building and testing, and specifying dependencies.
src/testing/CHANGELOG.md: Added a changelog file to document notable changes in the project, adhering to the Keep a Changelog format and Semantic Versioning.

Configuration and Build Tools:

src/testing/jest.config.js: Added a Jest configuration file to set up the testing environment for the package, including presets and transform ignore patterns.
tsconfig.testing.json: Created a TypeScript configuration file specifically for the testing package to manage compilation settings and include/exclude patterns.
src/testing/copy-bindings.js: Added a script to copy bindings from the build directory to the distribution directory.

Exporting Utilities:

src/testing/index.ts: Created an index file to export all testing utilities from the src/testing.js file.
src/testing/src/testing.ts: Imported and re-exported various utilities from equivalent.js, property.js, and constraint-system.js to make them available as part of the testing package.
src/lib/testing/equivalent.ts: Updated the export statement to include AnyTupleFunction.

TODO

This PR will have couple of follow-up tasks and PR's for:

Creating namespaces in src/lib/testing for better organization of tools
Adding TSDoc style comments to src/lib/testing
Discuss creating a packages directory for o1js,mina-signer and @o1js/testing internally.

src/testing/package.json

45930

Overall this looks reasonable! Can I try using it locally with npm link? I tried from the src/lib/testing folder and it didn't work.

src/testing/README.md

boray · 2025-04-03T20:50:29Z

Overall this looks reasonable! Can I try using it locally with npm link? I tried from the src/lib/testing folder and it didn't work.

I used yalc to test the package so far. It should work with npm link too. Can you explain how it failed?

45930 · 2025-04-04T00:13:38Z

For example, the react testing library doesn’t have a code block to install react. It just mentions that it’s a peer dependency. https://github.com/testing-library/react-testing-library I don’t think it’s a big deal either way. But it just seems like anyone installing this package will know how to install o1js too. On Thu, Apr 3, 2025 at 4:50 PM, Boray Saygılıer ***@***.***> wrote: Overall this looks reasonable! Can I try using it locally with npm link? I tried from the src/lib/testing folder and it didn't work. I used yalc to test the package so far. It should work with npm link too. Can you explain how it failed?— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you commented.Message ID: ***@***.***> boray left a comment (o1-labs/o1js#2093) Overall this looks reasonable! Can I try using it locally with npm link? I tried from the src/lib/testing folder and it didn't work. I used yalc to test the package so far. It should work with npm link too. Can you explain how it failed? — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you commented.Message ID: ***@***.***>

boray · 2025-04-04T00:19:42Z

I don’t think it’s a big deal either way. But it just seems like anyone installing this package will know how to install o1js too.

oops, I missed it's for o1js not @o1js/testing. Indeed, it's an overkill. I changed this while ago but not commited. It just has a note about peer dependency. The current version of the readme is incomplete. I'll be pushing updates tomorrow.

Trivo25 · 2025-04-04T05:15:38Z

src/testing/package.json

+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p ../../tsconfig.testing.json &&  node copyBindings.js",


right now this builds everything in the project, incl. mina-signer, and copies all artefacts into **/testing/dist/** - I think we should be a bit more selective here and only copy what we need

Only mina-signer is not used, but I didn't try to prevent it from building since npm run build in o1js also builds mina-signer.

src/testing/copyBindings.js

mitschabaude · 2025-04-04T06:49:47Z

src/testing/src/testing.ts

+export const {
+  constraintSystem,
+  not,
+  and,
+  or,
+  fulfills,
+  equals,
+  contains,
+  allConstant,
+  ifNotAllConstant,
+  isEmpty,
+  withoutGenerics,
+  print,
+  repeat,
+} = ConstraintSystem_;


I would put the constraint system stuff in a separate name space.
most people won't need it, and it's confusing to pollute the name space with many simple functions like and, equals etc

similar how Random is exported as its own namespace!

Agreed but then existing tests would be incompatible* (directly) with the package. What do you think about a new PR that creates such namespace and updates all tests?

wdym they "would be incompatible"? I'm asking for a change in this file, testing.ts, not in the existing tests

Suggested change

export const {

constraintSystem,

not,

and,

or,

fulfills,

equals,

contains,

allConstant,

ifNotAllConstant,

isEmpty,

withoutGenerics,

print,

repeat,

} = ConstraintSystem_;

export { ConstraintSystem_ as ConstraintSystem }

It was a deliberate choice to not create a namespace to not change the usage from constraintSystem.fromZkProgram() to ConstraintSystem.constraintSystem.fromZkProgram() to make the package "plug and play" compatible with the existing tests.

Wrong choice IMO. People won't use this, it pollutes the namespace, and it's still plug and play compatible if you just unpack the CobstraintSystem object at the beginning

"it pollutes the namespace" I agree with this but I don't think the latter is a good solution. Why not we fix the pollution in its roots at constraint-system.ts? Similar fix would be needed for equivalent.ts too.

Sure, fix it where you think it fits best!

I think this is one of those things where it's better to get it merged and change the namespace as a follow-up PR. I like to follow the "minimally invasive migration" => "improve" flow.

But I do agree that namespaceing would make sense.

A nice stopgap would be to do both (redundantly), have all the docs point to the namespace, and then migrate the old stuff. We can do this before releasing the npm package so that people don't use it/changing the API won't be a breaking change.

src/testing/README.md

Trivo25 · 2025-04-07T20:23:19Z

How do you want to release this to npm, if at all?

We can release as a scoped package under o1js on demand similar to mina-signer.

Right, but manually or through CI?

Manually, I don't think we should release this package in a strict cadence.

Okay, but this means the person releasing it will need access to our npm details. If we add a CI workflow we could trigger it manually, given we already have access to the credentials in CI

boray · 2025-04-07T20:25:31Z

How do you want to release this to npm, if at all?

We can release as a scoped package under o1js on demand similar to mina-signer.

Right, but manually or through CI?

Manually, I don't think we should release this package in a strict cadence.

Okay, but this means the person releasing it will need access to our npm details. If we add a CI workflow we could trigger it manually, given we already have access to the credentials in CI

I assumed you have the credentials for npm for o1js and you can release on my behalf. No worries, there won't be releases often :)

richardpringle

My only real change requests are in

src/testing/src/testing.ts
src/testing/package.json

I do think that everything else I've said is worth considering but should not block this PR

richardpringle · 2025-04-07T20:15:37Z

src/testing/CHANGELOG.md

So... this might be a hot-take, but I would love to see us be a little more organized with our directory structure. It would be really nice to have a top-level packages directory where this stuff would fit into packages/testing and the actual source-code files would be the only thing in the src directory.

I am onboard with this idea!

richardpringle · 2025-04-07T20:21:35Z

src/testing/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog


Goes alogn with my other comment, but if got a little more organized with our directory structure, we can check the diff for changes in packages/<package-name> and check packages/<package-name>/CHANGELOG.md for every package that has a diff.

src/testing/README.md

richardpringle · 2025-04-07T20:24:11Z

src/testing/README.md

The level of detail here is fantastic 🏆

I do think it would be beneficial to have a bunch of this directly alongside the code in tsdoc, but I think that could happen in a follow up and should not hold up landing this PR

src/testing/copy-bindings.js

richardpringle · 2025-04-07T20:46:34Z

src/testing/src/testing.ts

+export const {
+  constraintSystem,
+  not,
+  and,
+  or,
+  fulfills,
+  equals,
+  contains,
+  allConstant,
+  ifNotAllConstant,
+  isEmpty,
+  withoutGenerics,
+  print,
+  repeat,
+} = ConstraintSystem_;


I think this is one of those things where it's better to get it merged and change the namespace as a follow-up PR. I like to follow the "minimally invasive migration" => "improve" flow.

But I do agree that namespaceing would make sense.

A nice stopgap would be to do both (redundantly), have all the docs point to the namespace, and then migrate the old stuff. We can do this before releasing the npm package so that people don't use it/changing the API won't be a breaking change.

tsconfig.testing.json

richardpringle · 2025-04-07T20:48:17Z

src/testing/README.md

+
+Check out [`src/lib/provable/test`](https://github.com/o1-labs/o1js/tree/main/src/lib/provable/test) directory for more examples.
+
+## API Reference


I don't think you should have an API-reference in the README as it's impossible to keep this up to date. This section should just be an instruction on how to build the tsdocs and the API reference should be in there.

(I think you can do this as a follow up though)

I think that also a good path. But, the tsdocs should be at relevant files in src/lib/testing, not in this package. I think it's acceptable to have this reference in the README. I don't think it would be hard to keep this up to date as the testing files wouldn't change much. And, if we decide to do a refactor, updating the docs must be part of the refactor.

We can do a follow up PR once we figure out how we will present this package's docs in the new o1js documentation.

I don't think it would be hard to keep this up to date as the testing files wouldn't change much

Even if this is true, all it takes is one change and it could lead to confusion. It's much better to have reference docs alongside code as reviewers can easily spot whether or not changes include doc changes. It's not that keeping a README up to date requires significant effort, but it's so easy to forget. It's also true of doc-comments and any inline comment in general, but it's easier to remember when the edit to the docs takes place in the same file.

But yeah... agree with this:

We can do a follow up PR once we figure out how we will present this package's docs in the new o1js documentation.

.github/workflows/pkg-pr-new-publish.yml

Co-authored-by: Richard Pringle <rpringle@circle-free.com>

richardpringle

I'm going to give this a ✅, but I would prefer (if we all agree) that we move this package to /packages/testing before landing this PR.

Trivo25 · 2025-04-08T09:12:05Z

I assumed you have the credentials for npm for o1js and you can release on my behalf. No worries, there won't be releases often :)

We shouldn’t depend on a single person who may or may not have the credentials to release a package. For our other releases, we already have access to the credentials via CI, and we should follow the same approach here. Since we're introducing this new package to developers, we can expect feedback and requests for improvements - which means we'll likely need to release more frequently. Relying on one individual creates an unnecessary bottleneck and adds avoidable overhead to what could be a much simpler process.

src/testing/README.md

0x471

It seems good to merge for now, and the folder structure can be improved in follow-up PRs.

src/testing/README.md

45930 · 2025-04-08T14:19:49Z

We shouldn’t depend on a single person who may or may not have the credentials to release a package. For our other releases, we already have access to the credentials via CI, and we should follow the same approach here.

Yeah, releasing the package automatically if the version is incremented seems best to me. How do we handle mina signer?

45930 · 2025-04-08T14:22:02Z

I'm going to give this a ✅, but I would prefer (if we all agree) that we move this package to /packages/testing before landing this PR.

I think a separate PR is ok because the scope should also include migrating mina-signer (and o1js itself?) to the packages folder. I wouldn't want to muddy this PR with extra diffs and potential issues from that. We can handle migrating all packages to a standardized format in one PR.

Trivo25 · 2025-04-08T15:11:59Z

How do we handle mina signer?

Same way. We can simply copy the workflow from here

o1js/.github/workflows/build-action.yml

Lines 286 to 371 in d6ae829

    
             Release-on-NPM: 
        
               if: github.ref == 'refs/heads/main' 
        
               timeout-minutes: 180 
        
               runs-on: ubuntu-latest 
        
               needs: [Build-And-Test-Server, Run-Unit-Tests, Build-And-Test-Web] 
        
               steps: 
        
                 - name: Restore repository 
        
                   uses: actions/cache@v4 
        
                   with: 
        
                     path: . 
        
                     key: repo-${{ github.sha }} 
        
                 - name: Setup Node 
        
                   uses: actions/setup-node@v4 
        
                   with: 
        
                     node-version: '20' 
        
                 - name: Build o1js 
        
                   run: | 
        
                     npm ci 
        
                     npm run prepublishOnly 
        
                 - name: Publish to NPM if version has changed 
        
                   id: publish 
        
                   uses: JS-DevTools/npm-publish@v3 
        
                   with: 
        
                     token: ${{ secrets.NPM_TOKEN }} 
        
                     strategy: upgrade 
        
                   env: 
        
                     INPUT_TOKEN: ${{ secrets.NPM_TOKEN }} 
        
                 - name: Configure Git 
        
                   run: | 
        
                     git config --local user.email "action@github.com" 
        
                     git config --local user.name "GitHub Action" 
        
                 - name: Tag new version 
        
                   if: ${{ steps.publish.outputs.type }} # https://github.com/JS-DevTools/npm-publish?tab=readme-ov-file#action-output 
        
                   env: 
        
                     GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 
        
                     RELEASED_VERSION: ${{ steps.publish.outputs.version }} 
        
                   run: | 
        
                     git tag $RELEASED_VERSION 
        
                     git push origin $RELEASED_VERSION 
        
                 - name: Create Release 
        
                   uses: ncipollo/release-action@v1 
        
                   if: success() 
        
                   with: 
        
                     token: ${{ secrets.GITHUB_TOKEN }} 
        
                     tag: ${{ steps.publish.outputs.version }} 
        
                     generateReleaseNotes: true 
        
                     name: Release ${{ steps.publish.outputs.version }} 
        
             Release-mina-signer-on-NPM: 
        
               if: github.ref == 'refs/heads/main' 
        
               timeout-minutes: 180 
        
               runs-on: ubuntu-latest 
        
               needs: [Build-And-Test-Server, Run-Unit-Tests, Build-And-Test-Web] 
        
               steps: 
        
                 - name: Restore repository 
        
                   uses: actions/cache@v4 
        
                   with: 
        
                     path: . 
        
                     key: repo-${{ github.sha }} 
        
                 - name: Setup Node 
        
                   uses: actions/setup-node@v4 
        
                   with: 
        
                     node-version: '20' 
        
                 - name: Build mina-signer 
        
                   run: | 
        
                     npm ci 
        
                     cd src/mina-signer 
        
                     npm ci 
        
                     npm run prepublishOnly 
        
                 - name: Publish to NPM if version has changed 
        
                   uses: JS-DevTools/npm-publish@v3 
        
                   with: 
        
                     token: ${{ secrets.NPM_TOKEN }} 
        
                     package: './src/mina-signer/package.json' 
        
                     strategy: upgrade 
        
                   env: 
        
                     INPUT_TOKEN: ${{ secrets.NPM_TOKEN }}

github-actions

please update the npm-deps-hash

npmDepsHash

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

I committed bot's suggestion.

Trivo25 · 2025-04-09T11:39:19Z

src/testing/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog


In a follow up PR we should also organize our github actions better. Right now everything is a bit chaotic

Trivo25 · 2025-04-09T11:55:27Z

src/testing/package.json

+    "node": "./dist/node/testing/index.js",
+    "default": "./dist/node/testing/index.js"
+  },
+  "files": [


We are including mina-signer and other internal dependencies in the package when we publish it to npm. While this might not be a big size increase in the overall package (given that the compile artefacts alone are about 45mb), it's still suboptiomal to include files that have nothing to do with the actual library in the released package

If or when we end up splitting everything into seperate package folders, we should definitely clean this up. So let's make sure we keep this in mind, I approve in hopes that we will follow up on this soon

boray added 14 commits March 11, 2025 18:00

feat: o1js testing package

965de87

docs: add readme

82ad71f

feat: add package prototype

c6923ba

fix: remove test command

2681874

chore: simplify tsconfig

a8246c8

feat: fix build

8e57f60

feat: add jest config

f633f9d

test: add a placeholder test

4fb2f98

docs: update readme

58be0b1

format: fix

dd318eb

chore: remove jest

b7bdec9

feat: break up tools

dd8f123

feat: export AnyTupleFunction

ddfd78a

refactor: compatibility with existing tests

a2335e1

boray changed the title ~~@o1js/testing prototype~~ @o1js/testing Mar 24, 2025

45930 reviewed Mar 24, 2025

View reviewed changes

src/testing/package.json Outdated Show resolved Hide resolved

boray added 4 commits March 24, 2025 18:44

chore: support o1js versions 2.0.0 and above

5972e99

refactor: simplify exports

42e058c

format: fix formatting

e093fec

docs: remove redundant comments

8d21f2f

45930 reviewed Apr 3, 2025

View reviewed changes

src/testing/README.md Outdated Show resolved Hide resolved

Trivo25 reviewed Apr 4, 2025

View reviewed changes

mitschabaude reviewed Apr 4, 2025

View reviewed changes

src/testing/copyBindings.js Outdated Show resolved Hide resolved

mitschabaude reviewed Apr 4, 2025

View reviewed changes

src/testing/README.md Outdated Show resolved Hide resolved

boray added 2 commits April 4, 2025 11:42

chore: rename script

4802c91

docs: update readme

79536b6

richardpringle requested changes Apr 7, 2025

View reviewed changes

boray and others added 8 commits April 7, 2025 23:57

chore: create scripts dir

2ff7700

Update src/testing/package.json

8e4ea07

Co-authored-by: Richard Pringle <rpringle@circle-free.com>

fix: script path

304e29b

fix: script path and add rimraf

b47a426

Update .github/workflows/pkg-pr-new-publish.yml

58d5582

Co-authored-by: Richard Pringle <rpringle@circle-free.com>

Update .github/workflows/pkg-pr-new-publish.yml

c6931d4

Co-authored-by: Richard Pringle <rpringle@circle-free.com>

format: add newlines

460e613

fix: remove testing.ts

d91f118

richardpringle approved these changes Apr 7, 2025

View reviewed changes

mitschabaude reviewed Apr 8, 2025

View reviewed changes

src/testing/README.md Outdated Show resolved Hide resolved

0x471 approved these changes Apr 8, 2025

View reviewed changes

src/testing/README.md Outdated Show resolved Hide resolved

boray added 4 commits April 9, 2025 01:54

ci: add release workflow

f56fd0e

docs: fix typos

ef4fac3

docs: fix inaccuracy

a02134f

ci: fix npmdepshash

3a983c7

github-actions bot previously requested changes Apr 8, 2025

View reviewed changes

npmDepsHash Outdated Show resolved Hide resolved

boray and others added 2 commits April 9, 2025 02:30

Update npmDepsHash

c3d561d

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

fix: eof issue

609aa8a

boray added the no changelog label Apr 8, 2025

Trivo25 approved these changes Apr 9, 2025

View reviewed changes

boray added 2 commits April 9, 2025 20:46

fix: configs to reflect deletion of testing.ts

8959da8

Merge branch 'main' into boray/o1js-testing

a0a3c91


		Check out [`src/lib/provable/test`](https://github.com/o1-labs/o1js/tree/main/src/lib/provable/test) directory for more examples.

		## API Reference

@o1js/testing #2093

Are you sure you want to change the base?

@o1js/testing #2093

Conversation

boray commented Mar 24, 2025 • edited Loading

New Package Setup:

Configuration and Build Tools:

Exporting Utilities:

TODO

45930 left a comment

Choose a reason for hiding this comment

boray commented Apr 3, 2025

45930 commented Apr 4, 2025 via email

boray commented Apr 4, 2025

Trivo25 Apr 4, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trivo25 commented Apr 7, 2025

boray commented Apr 7, 2025

richardpringle left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richardpringle left a comment

Choose a reason for hiding this comment

Trivo25 commented Apr 8, 2025

0x471 left a comment

Choose a reason for hiding this comment

45930 commented Apr 8, 2025

45930 commented Apr 8, 2025

Trivo25 commented Apr 8, 2025

github-actions bot left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

boray commented Mar 24, 2025 •

edited

Loading

Trivo25 Apr 4, 2025 •

edited

Loading