From 4e7e7acfbfb74264b8df459697f2c430e3fcd480 Mon Sep 17 00:00:00 2001
From: Eric Warehime <eric.warehime@gmail.com>
Date: Wed, 20 Dec 2023 11:49:11 -0600
Subject: [PATCH] chore: Add e2e test readme (#319)

---
 .github/workflows/test.yml |  1 +
 Makefile                   |  2 +-
 tests/e2e/README.md        | 57 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 tests/e2e/README.md

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 99ea667..18bc451 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -37,6 +37,7 @@ jobs:
           make test-unit
       - name: Test Coverage
         run: |
+          go work init ||:
           make test-cover
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v3
diff --git a/Makefile b/Makefile
index 398874e..d873780 100644
--- a/Makefile
+++ b/Makefile
@@ -136,7 +136,7 @@ test-unit: use-main
 test-integration: tidy
 	@go test -v -race ./tests/integration/... 
 
-test-cover: tidy
+test-cover: use-main tidy
 	@echo Running unit tests and creating coverage report...
 	@go test -mod=readonly -v -timeout 30m -coverprofile=$(COVER_FILE) -covermode=atomic $(shell go list ./... | grep -v tests/)
 	@sed -i '/.pb.go/d' $(COVER_FILE)
diff --git a/tests/e2e/README.md b/tests/e2e/README.md
new file mode 100644
index 0000000..f617c93
--- /dev/null
+++ b/tests/e2e/README.md
@@ -0,0 +1,57 @@
+# Block SDK E2E Tests
+
+## Integrating/Running Tests In Your Project
+
+The Block SDK E2E tests are built around [interchaintest](https://github.com/strangelove-ventures/interchaintest). To run the 
+full set of predefined test cases using your chain you can follow the steps below:
+
+### Integrate the Block SDK into your project  
+
+You will need to pull in the Block SDK as a dependency of your project. You can follow the guides located in 
+[our integration docs](https://docs.skip.money/chains/integrate-the-sdk/) or [this README](../../tests/app/README.md) for detailed instructions.  
+You can refer to [this PR](https://github.com/CascadiaFoundation/cascadia/pull/33) as one example of how the Block SDK
+can be integrated into an application. Be aware that each chain will have different requirements and this example may
+not be fully applicable to yours. Additionally, future versions may introduce new requirements.
+
+### Define a container image  
+
+Interchaintest will require a Docker image in order to spin up your chain's application. If you do not already have a
+container build setup that launches your application's binary you will need to define one.  
+An example of the Block SDK's test app's Docker build can be referenced [here](../../contrib/images/block-sdk.e2e.Dockerfile).
+
+### Create an InterchainTest Chain Spec  
+
+The test suite uses the [interchaintest.ChainSpec](https://github.com/strangelove-ventures/interchaintest/blob/main/chainspec.go)
+to define the specifics around running your application. You'll need to define the number of validator and full node containers to run, the docker image, the genesis state,
+encoding config, and various other variables.  
+Some examples of ChainSpecs follow:
+
+* [Block SDK testappd](https://github.com/skip-mev/block-sdk/blob/335d7a216aaca757fee40a1ed63e13061e79b39d/tests/e2e/block_sdk_e2e_test.go#L71)
+* [Cascadia](https://github.com/CascadiaFoundation/cascadia/blob/main/interchaintest/block_sdk_test.go)
+
+### Instantiate the test suite and run the tests  
+
+You will need to pull the Block SDK's tests into your project as a separate dependency. It might be useful to do this in
+a separate go submodule specifically for running these tests ([for example](https://github.com/CascadiaFoundation/cascadia/tree/main/interchaintest))
+
+```text
+github.com/skip-mev/block-sdk/tests/integration {vLatest}
+```
+
+The following snippet is usually suitable.
+
+```go
+func TestBlockSDKSuite(t *testing.T) {
+	s := integration.NewIntegrationTestSuiteFromSpec(spec)
+	s.WithDenom(denom)
+	s.WithKeyringOptions(encodingConfig.Codec, keyring.Option())
+	suite.Run(t, s)
+```
+
+### Run the tests
+
+Add a separate makefile target to run your tests.
+
+```shell
+go test -v -race -run TestBlockSDKSuite
+```