A tab switch costs a train of thought. Testing smart contracts inside the docs.

A Web3 developer integrating Lido into their dApp needs to test contract functions as they read. Without somewhere to do that in the page, the work splinters: open a separate testing environment, move between tabs, rebuild your place each time you come back. One Slack message and the thread is gone.

That is a productivity problem for the developer and an adoption problem for whoever wrote the documentation. Every interruption between reading and testing is a chance to give up on the integration. Bonadocs wanted the testing to happen where the reading already was.

We ran Jobs-to-be-Done interviews with eight Web3 developers from mid-sized blockchain companies, averaging five years in software and two in Web3, working across Solidity, JavaScript, React, Node, MetaMask, Truffle, Remix and Ganache. The questions were about their day rather than about the widget: what they were trying to get done, and what got in the way.

What they told us

Testing was not an occasional task, it was continuous. “Testing smart contracts is a constant part of my workflow. I need to ensure each function works as expected before moving on.” And the tooling around it was the friction, not the testing itself: “It feels like I spend more time managing tools than actually coding.”

If I could test smart contracts directly in the docs, it would streamline my workflow and reduce the cognitive load of switching between tools.

Mapping the journey put the breaks in one picture. Every one of them sat at a boundary between two tools, and none of them were about the contract logic. That is what told us the widget was worth building: the problem was entirely in the seams.

Embedding an interactive testing environment inside Lido's documentation raised four questions we could not answer up front. Would a widget disrupt the reading experience it sat in? Could it be intuitive enough to use without a learning curve? How should it handle complex transaction parameters? And was querying the mainnet directly from a documentation page even feasible, let alone safe?

Prototype rough, test early

We clustered the first round of usability feedback with affinity diagramming to find the themes underneath individual complaints, then moved fast into low fidelity. The Bonadocs design system already existed, which meant prototypes could be assembled rather than drawn, and tested with users while they were still cheap to throw away.

What the second round changed

Round two tested six specific changes: transaction parameters entered inside the widget rather than elsewhere, a mainnet query option for real simulations, a wallet connection flow with a visible connected state, tooltips describing what each method parameter does, a tab view for constant transaction parameters like From, Gas and Gas price, and a clear visual split between read and write methods.

Participants singled out the same thing: being able to test a method in the page they were reading, against the live network, without arranging anything first.

Querying the mainnet from the documentation

Connecting a wallet and running against mainnet is what makes the result trustworthy. A test that only proves the shape of a call is a test you still have to repeat somewhere else before you ship.

Array properties, so real contracts fit

Methods that take tuples of parameters are ordinary in production contracts and impossible to express in a simple form. Supporting arrays is what moved the widget from demo to usable.

Method and transaction parameters, kept apart

The two sets of parameters do different jobs and get confused constantly. Separating them into tabs removed a whole class of error without needing to explain anything.

Protocols using it, including Arbitrum, Optimism, Compound and Base

7+

Selected for the maiden Consensys program

Fellowship

The widget is now used and supported by Arbitrum, Superfluid, Compound Finance, Optimism, Base and Paycrest among others, and the work was selected for the first Consensys fellowship. Adoption by protocol teams is the honest measure here: they only embed it if it makes their own documentation better.

Nothing about this made testing smarter. It made it local. The widget does what a separate testing environment already did, in the one place the developer was already looking, and that turned out to be the entire value.

It also had to be a good guest. The widget lives inside documentation somebody else owns and maintains, which set a hard limit on how much room it could take and how much it could assume. Designing to be unobtrusive in someone else's product is a different discipline from designing your own.