Skip to content

docs: how hegel works - minor punctuation edits and line edit #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ink7047 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: how hegel works - minor punctuation edits and line edit #65

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/content/docs/explanation/how-hegel-works.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: How Hegel works

At the highest level, Hegel defines a *protocol* for communication between a *server* and a *client*.

- The server implements the core of property-based testing. Data generation, shrinking, and so on.
- The server implements the core of property-based testing: data generation, shrinking, and so on.
- The client implements the user-facing syntax of properties and generators. It asks the server for generated data via protocol requests.

:::note
Expand All @@ -26,7 +26,7 @@ fn test_a(tc: TestCase) {
When this test runs:

- If this is the first Hegel test to run in the test suite, `hegel-rust` spawns the server as a subprocess and negotiates an initial handshake with it. This negotiated connection and subprocess is then reused for any further tests.
- The handshake is for example used to communicate the server version to `hegel-rust`.
- The handshake is, for example, used to communicate the server version to `hegel-rust`.
- `hegel-rust` tells the server a new test is being run, and with what settings. Here, the settings are `test_cases=200`.
- `hegel-rust` tells the server a new test case is being started.
- `hegel-rust` executes `test_a` for that test case. When `tc.draw` is called, `hegel-rust` sends the schema representing the generator to the server. The server generates an arbitrary matching value and returns it.
Expand All @@ -35,6 +35,6 @@ When this test runs:
- After 200 test cases, the test finishes. `hegel-rust` communicates this to the server.
- If the test fails, `hegel-rust` communicates this to the server. The server then shrinks the failing test case and returns the minimal failing test case to `hegel-rust`, who displays it to the user.

The transport layer of the protocol is currently unix sockets, but the protocol is agnostic to the particular choice of transport layer and this could in principle be swapped for something else.
The transport layer of the protocol is currently unix sockets, but the protocol is agnostic to the particular choice of transport layer and this could, in principle, be swapped for something else.

We have glossed over some subtlety here. For example, `tc.assume()` and `generator.filter()` can reject test cases during the test, which needs to be communicated back to the server. And the server needs the ability to communicate errors to the client, for example in the case of a flaky test or an invalid generator definition.
We glossed over some subtlety here. For example, `tc.assume()` and `generator.filter()` can reject test cases during the test, which needs to be communicated back to the server. And the server needs the ability to communicate errors to the client, for example in the case of a flaky test or an invalid generator definition.