> For the complete documentation index, see [llms.txt](https://serverlessguru.gitbook.io/sls-jest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://serverlessguru.gitbook.io/sls-jest/matchers/s3.md).

# S3

A collection of matchers that you can use to assert on S3 bucket objects.

Use the `s3Object()` helper function to specify which S3 object you are testing. It takes the following input parameters:

* `bucketName`: The bucket name where the object should be found.
* `key`: They key of the object you are looking for
* `retryPolicy`: An optional [node-retry](https://github.com/tim-kos/node-retry) options config. `sls-jest` will retry using the given retry policy until the test passes or all the retries are exhausted. This is useful in an asynchronous context.

### `toExist()`

Asserts whether an S3 object exists in the given bucket.

```typescript
await expect(
  s3Object({
    bucketName: 'my-bucket',
    key: 'path/to/file.txt',
  }),
).toExist();
```

### `toExistAndMatchObject<E>(expected: DeepPartial<E>)`

Asserts that an object exists in the given bucket, and matches a subset of the properties of a javascript object. It works similarly to jest's [toMatchObject](https://jestjs.io/docs/expect#tomatchobjectobject).

Note: This matcher can only be used with S3 objects that contain JSON-like data. If the content of the file cannot be parsed to a valid JSON, an error will be thrown.

```typescript
await expect(
  s3Object({
    bucketName: 'my-bucket',
    key: 'path/to/file.txt',
  }),
).toExistAndMatchObject<Message>({
  message: 'Hello world!',
});
```

### `toExistAndMatchSnapshot(propertiesOrHint?: string, hint?: string)`

Asserts that an item exists in the given bucket, and that it matches the most recent snapshot. It works similarly to jest's [toMatchSnapshot](https://jestjs.io/docs/expect#tomatchsnapshotpropertymatchers-hint).

```typescript
await expect(
  s3Object({
    bucketName: 'my-bucket',
    key: 'path/to/file.txt',
  }),
).toExistAndMatchSnapshot();
```

### `toExistAndMatchInlineSnapshot(propertiesOrHint?: string, hint?: string)`

Asserts that an object exists in the given bucket, and that it matches the most recent inline snapshot. It works similarly to jest's [toMatchInlineSnapshot](https://jestjs.io/docs/expect#tomatchinlinesnapshotpropertymatchers-inlinesnapshot).

```typescript
await expect(
  s3Object({
    bucketName: 'my-bucket',
    key: 'path/to/file.txt',
  }),
).toExistAndMatchInlineSnapshot(`
  Object {
    "message": 'Hello world!',
  }
`);
```