Skip to content

Commit 68c6caf

Browse files
BigBlueHatBigBlueHat
committed
Reorganize README and update its ToC.
1 parent 1ccfb72 commit 68c6caf

File tree

1 file changed

+115
-114
lines changed

1 file changed

+115
-114
lines changed

‎README.md

+115-114
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,11 @@ specification.
1616
- [Background](#background)
1717
- [Install](#install)
1818
- [Setup](#setup)
19-
- [Test Suite HTTP API](#test-suite-http-api)
2019
- [Usage](#usage)
2120
- [Testing Locally](#testing-locally)
2221
- [Allure Reporting](#allure-reporting)
2322
- [Implementation](#implementation)
24-
- [VC-API](#vc-api)
23+
- [Test Suite HTTP API](#test-suite-http-api)
2524
- [Enveloping Proof](#enveloping-proof)
2625
- [Contribute](#contribute)
2726
- [License](#license)
@@ -57,6 +56,120 @@ be submitted for verification. Signed Verifiable Presentations from this suite
5756
will have a domain and challenge set. The domain should be the test repo, and
5857
the challenge is static.
5958

59+
#### Required Contexts
60+
61+
Implementations are expected to not error when any of the following context
62+
files are used in a verifiable credential or a verifiable presentation:
63+
64+
- [VC 2.0 Context - https://www.w3.org/ns/credentials/v2](https://www.w3.org/ns/credentials/v2)
65+
- [VC Examples Context - https://www.w3.org/ns/credentials/examples/v2](https://www.w3.org/ns/credentials/examples/v2)
66+
67+
## Usage
68+
69+
To add your implementation to this test suite, add a test manifest describing
70+
your implementation to the
71+
[`w3c/vc-test-suite-implementations`](https://github.com/w3c/vc-test-suite-implementations)
72+
repo by following the
73+
[Adding a new implementation](https://github.com/w3c/vc-test-suite-implementations/tree/main?tab=readme-ov-file#adding-a-new-implementation)
74+
instructions.
75+
76+
All endpoints will need the tag `vc2.0`. A simplified manifest will roughly
77+
look like the following:
78+
79+
```js
80+
{
81+
"name": "My Company",
82+
"implementation": "My implementation",
83+
"issuers": [{
84+
"id": "",
85+
"endpoint": "https://issuer.mycompany.com/credentials/issue",
86+
"tags": ["vc2.0"]
87+
}],
88+
"verifiers": [{
89+
"id": "",
90+
"endpoint": "https://verifier.mycompany.com/credentials/verify",
91+
"tags": ["vc2.0"]
92+
}],
93+
"vpVerifiers": [{
94+
"id": "",
95+
"endpoint": "https://verifier.mycompany.com/presentations/verify",
96+
"tags": ["vc2.0"]
97+
}]
98+
}
99+
```
100+
101+
The example above is for a set of unauthenticated endpoints. You can add
102+
[ZCAP](https://w3c-ccg.github.io/zcap-spec/)
103+
or [OAuth2 authentication](https://oauth.net/2/client-authentication/) to your endpoints.
104+
105+
See
106+
[Adding a new implementation](https://github.com/w3c/vc-test-suite-implementations/tree/main?tab=readme-ov-file#adding-a-new-implementation)
107+
for more information.
108+
109+
### Testing Locally
110+
111+
To test a single implementation or endpoint running locally, you can
112+
copy `localConfig.example.cjs` to `localConfig.cjs`
113+
in the root directory of the test suite.
114+
115+
```bash
116+
cp localConfig.example.cjs localConfig.cjs
117+
```
118+
119+
This file must be a CommonJS module that exports an object containing a
120+
`settings` object (for configuring the test suite code itself) and an
121+
`implementations` array (for configuring the implementation(s) to test against).
122+
123+
The format of the object contained in the `implementations` array is
124+
identical to the one defined in
125+
[the **_Testing locally_** section of VC Test Suite Implementations](https://github.com/w3c/vc-test-suite-implementations?tab=readme-ov-file#testing-locally).
126+
The `implementations` array may contain more than one implementation object,
127+
enabling you to test multiple implementations in one run.
128+
129+
```js
130+
// localConfig.cjs defines local implementations
131+
// Before running the tests, you can specify a BASE_URL, such as
132+
// BASE_URL=http://localhost:40443/zDdfsdfs npm test
133+
const baseUrl = process.env.BASE_URL || 'https://localhost:40443/id';
134+
module.exports = {
135+
settings: {
136+
enableInteropTests: false, // default
137+
testAllImplementations: false // default
138+
},
139+
implementations: [{
140+
name: 'My Company',
141+
implementation: 'My Implementation Name',
142+
issuers: [{
143+
id: 'did:myMethod:implementation:issuer:id',
144+
endpoint: `${baseUrl}/credentials/issue`
145+
}],
146+
verifiers: [{
147+
id: 'did:myMethod:implementation:verifier:id',
148+
endpoint: `${baseUrl}/credentials/verify`
149+
}]
150+
}];
151+
```
152+
153+
Then...
154+
155+
```sh
156+
npm test
157+
```
158+
159+
### Allure Reporting
160+
It's also possible to generate local allure reports for analyzing and debugging results. [Allure](https://allurereport.org/) is a language agnostic reporting framework which enables useful features for developers and test-suite designers.
161+
162+
To run the tests and browse the report, use the following commands:
163+
```bash
164+
# Running the tests
165+
npx mocha tests/
166+
167+
# Running the reporting server
168+
allure serve allure-results
169+
```
170+
171+
## Implementation
172+
60173
### Test Suite HTTP API
61174
62175
@@ -260,118 +373,6 @@ HTTP/1.1 200 OK
260373
The presentation verifier endpoint is based on the
261374
[VC API Verify Presentation](https://w3c-ccg.github.io/vc-api/#verify-presentation) endpoint.
262375
263-
#### Required Contexts
264-
265-
Implementations are expected to not error when any of the following context
266-
files are used in a verifiable credential or a verifiable presentation:
267-
268-
- [VC 2.0 Context - https://www.w3.org/ns/credentials/v2](https://www.w3.org/ns/credentials/v2)
269-
- [VC Examples Context - https://www.w3.org/ns/credentials/examples/v2](https://www.w3.org/ns/credentials/examples/v2)
270-
271-
## Usage
272-
273-
```sh
274-
npm test
275-
```
276-
277-
### Testing Locally
278-
279-
To test a single implementation or endpoint running locally, you can
280-
copy `localConfig.example.cjs` to `localConfig.cjs`
281-
in the root directory of the test suite.
282-
283-
```bash
284-
cp localConfig.example.cjs localConfig.cjs
285-
```
286-
287-
This file must be a CommonJS module that exports an object containing a
288-
`settings` object (for configuring the test suite code itself) and an
289-
`implementations` array (for configuring the implementation(s) to test against).
290-
291-
The format of the object contained in the `implementations` array is
292-
identical to the one defined in
293-
[the **_Testing locally_** section of VC Test Suite Implementations](https://github.com/w3c/vc-test-suite-implementations?tab=readme-ov-file#testing-locally).
294-
The `implementations` array may contain more than one implementation object,
295-
enabling you to test multiple implementations in one run.
296-
297-
```js
298-
// localConfig.cjs defines local implementations
299-
// Before running the tests, you can specify a BASE_URL, such as
300-
// BASE_URL=http://localhost:40443/zDdfsdfs npm test
301-
const baseUrl = process.env.BASE_URL || 'https://localhost:40443/id';
302-
module.exports = {
303-
settings: {
304-
enableInteropTests: false, // default
305-
testAllImplementations: false // default
306-
},
307-
implementations: [{
308-
name: 'My Company',
309-
implementation: 'My Implementation Name',
310-
issuers: [{
311-
id: 'did:myMethod:implementation:issuer:id',
312-
endpoint: `${baseUrl}/credentials/issue`
313-
}],
314-
verifiers: [{
315-
id: 'did:myMethod:implementation:verifier:id',
316-
endpoint: `${baseUrl}/credentials/verify`
317-
}]
318-
}];
319-
```
320-
321-
### Allure Reporting
322-
It's also possible to generate local allure reports for analyzing and debugging results. [Allure](https://allurereport.org/) is a language agnostic reporting framework which enables useful features for developers and test-suite designers.
323-
324-
To run the tests and browse the report, use the following commands:
325-
```bash
326-
# Running the tests
327-
npx mocha tests/
328-
329-
# Running the reporting server
330-
allure serve allure-results
331-
```
332-
333-
## Implementation
334-
335-
To add your implementation to this test suite, add a test manifest describing
336-
your implementation to the
337-
[`w3c/vc-test-suite-implementations`](https://github.com/w3c/vc-test-suite-implementations)
338-
repo by following the
339-
[Adding a new implementation](https://github.com/w3c/vc-test-suite-implementations/tree/main?tab=readme-ov-file#adding-a-new-implementation)
340-
instructions.
341-
342-
All endpoints will need the tag `vc2.0`. A simplified manifest will roughly
343-
look like the following:
344-
345-
```js
346-
{
347-
"name": "My Company",
348-
"implementation": "My implementation",
349-
"issuers": [{
350-
"id": "",
351-
"endpoint": "https://issuer.mycompany.com/credentials/issue",
352-
"tags": ["vc2.0"]
353-
}],
354-
"verifiers": [{
355-
"id": "",
356-
"endpoint": "https://verifier.mycompany.com/credentials/verify",
357-
"tags": ["vc2.0"]
358-
}],
359-
"vpVerifiers": [{
360-
"id": "",
361-
"endpoint": "https://verifier.mycompany.com/presentations/verify",
362-
"tags": ["vc2.0"]
363-
}]
364-
}
365-
```
366-
367-
The example above is for a set of unauthenticated endpoints. You can add
368-
[ZCAP](https://w3c-ccg.github.io/zcap-spec/)
369-
or [OAuth2 authentication](https://oauth.net/2/client-authentication/) to your endpoints.
370-
371-
See
372-
[Adding a new implementation](https://github.com/w3c/vc-test-suite-implementations/tree/main?tab=readme-ov-file#adding-a-new-implementation)
373-
for more information.
374-
375376
### Enveloping Proof
376377
Implementers who rely on an enveloping proof securing mechanism can add the `EnvelopingProof` tag to their implementation registration.
377378

0 commit comments

Comments
 (0)