local-web-services-javascript-sdk 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +132 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# local-web-services-javascript-sdk
|
|
2
|
+
|
|
3
|
+
JavaScript testing SDK for [local-web-services](https://github.com/local-web-services/local-web-services) — spawns `ldk dev` in a subprocess and provides pre-configured AWS SDK v3 clients for testing.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
Install `local-web-services`:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pip install local-web-services
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install local-web-services-javascript-sdk
|
|
17
|
+
# or
|
|
18
|
+
pnpm add local-web-services-javascript-sdk
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Quick start
|
|
22
|
+
|
|
23
|
+
```js
|
|
24
|
+
const { LwsSession } = require('local-web-services-javascript-sdk');
|
|
25
|
+
|
|
26
|
+
// Auto-discover from a CDK project (runs ldk dev against cdk.out/)
|
|
27
|
+
const session = await LwsSession.fromCdk('../my-cdk-project');
|
|
28
|
+
|
|
29
|
+
// Auto-discover from a Terraform project
|
|
30
|
+
const session = await LwsSession.fromHcl('../my-terraform-project');
|
|
31
|
+
|
|
32
|
+
// Explicit resource declaration
|
|
33
|
+
const session = await LwsSession.create({
|
|
34
|
+
tables: [{ name: 'Orders', partitionKey: 'id' }],
|
|
35
|
+
queues: ['OrderQueue'],
|
|
36
|
+
buckets: ['ReceiptsBucket'],
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
// Get a fully-configured AWS SDK v3 client
|
|
40
|
+
const dynamodb = session.client('dynamodb');
|
|
41
|
+
|
|
42
|
+
// Use the helper API
|
|
43
|
+
const table = session.dynamodb('Orders');
|
|
44
|
+
await table.put({ id: { S: '1' }, status: { S: 'pending' } });
|
|
45
|
+
const items = await table.scan();
|
|
46
|
+
console.log(items.length); // 1
|
|
47
|
+
|
|
48
|
+
// Always close the session when done
|
|
49
|
+
await session.close();
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Jest example
|
|
53
|
+
|
|
54
|
+
```js
|
|
55
|
+
// jest.config.js
|
|
56
|
+
module.exports = {
|
|
57
|
+
testEnvironment: 'node',
|
|
58
|
+
testTimeout: 60000, // ldk dev needs time to start
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
// orders.test.js
|
|
62
|
+
const { LwsSession } = require('local-web-services-javascript-sdk');
|
|
63
|
+
|
|
64
|
+
let session;
|
|
65
|
+
|
|
66
|
+
beforeAll(async () => {
|
|
67
|
+
session = await LwsSession.create({
|
|
68
|
+
tables: [{ name: 'Orders', partitionKey: 'id' }],
|
|
69
|
+
});
|
|
70
|
+
});
|
|
71
|
+
|
|
72
|
+
afterAll(async () => {
|
|
73
|
+
await session.close();
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
beforeEach(async () => {
|
|
77
|
+
await session.reset();
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
test('creates an order', async () => {
|
|
81
|
+
const table = session.dynamodb('Orders');
|
|
82
|
+
await table.put({ id: { S: '42' }, status: { S: 'pending' } });
|
|
83
|
+
|
|
84
|
+
const item = await table.assertItemExists({ id: { S: '42' } });
|
|
85
|
+
expect(item.status.S).toBe('pending');
|
|
86
|
+
});
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Drop-in AWS endpoint redirection
|
|
90
|
+
|
|
91
|
+
When a session starts, `AWS_ENDPOINT_URL_*` environment variables are automatically set for all supported services. Any AWS SDK v3 client created after the session starts — including clients in your production code — will hit the local LWS services without any code changes:
|
|
92
|
+
|
|
93
|
+
```js
|
|
94
|
+
// production code
|
|
95
|
+
const { DynamoDBClient } = require('@aws-sdk/client-dynamodb');
|
|
96
|
+
const client = new DynamoDBClient({}); // picks up AWS_ENDPOINT_URL_DYNAMODB automatically
|
|
97
|
+
|
|
98
|
+
// test code — no endpoint configuration needed
|
|
99
|
+
const session = await LwsSession.create({ tables: [{ name: 'Orders', partitionKey: 'id' }] });
|
|
100
|
+
// production client now talks to LWS
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Env vars are restored when `session.close()` is called.
|
|
104
|
+
|
|
105
|
+
## API
|
|
106
|
+
|
|
107
|
+
### `LwsSession`
|
|
108
|
+
|
|
109
|
+
| Method | Description |
|
|
110
|
+
|--------|-------------|
|
|
111
|
+
| `LwsSession.create(spec)` | Start with explicit resource spec |
|
|
112
|
+
| `LwsSession.fromCdk(projectDir)` | Auto-discover from CDK cloud assembly |
|
|
113
|
+
| `LwsSession.fromHcl(projectDir)` | Auto-discover from Terraform `.tf` files |
|
|
114
|
+
| `session.client(service)` | Get AWS SDK v3 client |
|
|
115
|
+
| `session.dynamodb(tableName)` | Get `DynamoDBHelper` |
|
|
116
|
+
| `session.sqs(queueName)` | Get `SQSHelper` |
|
|
117
|
+
| `session.s3(bucketName)` | Get `S3Helper` |
|
|
118
|
+
| `session.reset()` | Clear all state (use in `beforeEach`) |
|
|
119
|
+
| `session.close()` | Stop `ldk dev` process |
|
|
120
|
+
| `session.queueUrl(queueName)` | Get local SQS queue URL |
|
|
121
|
+
| `session.portFor(service)` | Get port number for a service |
|
|
122
|
+
| `session.mock(service)` | Get `MockBuilder` for service |
|
|
123
|
+
| `session.chaos(service)` | Get `ChaosBuilder` for service |
|
|
124
|
+
| `session.iam` | Get `IamBuilder` |
|
|
125
|
+
|
|
126
|
+
### Supported services
|
|
127
|
+
|
|
128
|
+
`dynamodb`, `s3`, `sqs`, `sns`, `ssm`, `secretsmanager`, `stepfunctions`
|
|
129
|
+
|
|
130
|
+
## License
|
|
131
|
+
|
|
132
|
+
MIT
|
package/package.json
CHANGED