diff --git a/.ci.readme.fmt.sh b/.ci.readme.fmt.sh new file mode 100755 index 000000000..6f1f3a269 --- /dev/null +++ b/.ci.readme.fmt.sh @@ -0,0 +1,10 @@ +#!/bin/bash + +# Verify that the code snippets in README.md are formatted. +# The tool https://github.com/hougesen/mdsf is used. + +if [ -n "$(mdsf verify --config .mdsf.json README.md 2>&1)" ]; then + echo "Go code in the README.md is not formatted." + echo "Did you forget to run 'mdsf format --config .mdsf.json README.md'?" + exit 1 +fi diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 1dd4e650f..ded4f06b5 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -37,3 +37,15 @@ jobs: with: go-version: ${{ matrix.go_version }} - run: go test -v -race ./... + format: + name: Check formatting of code snippets in markdown files + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: stable + - run: npm install -g mdsf-cli + - run: ./.ci.gofmt.sh + - run: ./.ci.readme.fmt.sh diff --git a/.mdsf.json b/.mdsf.json new file mode 100644 index 000000000..7617589ce --- /dev/null +++ b/.mdsf.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://raw.githubusercontent.com/hougesen/mdsf/main/schemas/v0.4.1/mdsf.schema.json", + "format_finished_document": false, + "languages": { + "go": [ + [ + "gofmt", + "goimports" + ] + ] + } +} diff --git a/README.md b/README.md index d4857d38f..44d40e6c4 100644 --- a/README.md +++ b/README.md @@ -38,30 +38,27 @@ See it in action: package yours import ( - "testing" - "github.com/stretchr/testify/assert" + "testing" + + "github.com/stretchr/testify/assert" ) func TestSomething(t *testing.T) { + // assert equality + assert.Equal(t, 123, 123, "they should be equal") - // assert equality - assert.Equal(t, 123, 123, "they should be equal") - - // assert inequality - assert.NotEqual(t, 123, 456, "they should not be equal") - - // assert for nil (good for errors) - assert.Nil(t, object) + // assert inequality + assert.NotEqual(t, 123, 456, "they should not be equal") - // assert for not nil (good when you expect something) - if assert.NotNil(t, object) { - - // now we know that object isn't nil, we are safe to make - // further assertions without causing any errors - assert.Equal(t, "Something", object.Value) - - } + // assert for nil (good for errors) + assert.Nil(t, object) + // assert for not nil (good when you expect something) + if assert.NotNil(t, object) { + // now we know that object isn't nil, we are safe to make + // further assertions without causing any errors + assert.Equal(t, "Something", object.Value) + } } ``` @@ -74,29 +71,29 @@ if you assert many times, use the below: package yours import ( - "testing" - "github.com/stretchr/testify/assert" + "testing" + + "github.com/stretchr/testify/assert" ) func TestSomething(t *testing.T) { - assert := assert.New(t) + assert := assert.New(t) - // assert equality - assert.Equal(123, 123, "they should be equal") + // assert equality + assert.Equal(123, 123, "they should be equal") - // assert inequality - assert.NotEqual(123, 456, "they should not be equal") + // assert inequality + assert.NotEqual(123, 456, "they should not be equal") - // assert for nil (good for errors) - assert.Nil(object) + // assert for nil (good for errors) + assert.Nil(object) - // assert for not nil (good when you expect something) - if assert.NotNil(object) { - - // now we know that object isn't nil, we are safe to make - // further assertions without causing any errors - assert.Equal("Something", object.Value) - } + // assert for not nil (good when you expect something) + if assert.NotNil(object) { + // now we know that object isn't nil, we are safe to make + // further assertions without causing any errors + assert.Equal("Something", object.Value) + } } ``` @@ -120,8 +117,9 @@ An example test function that tests a piece of code that relies on an external o package yours import ( - "testing" - "github.com/stretchr/testify/mock" + "testing" + + "github.com/stretchr/testify/mock" ) /* @@ -130,8 +128,8 @@ import ( // MyMockedObject is a mocked object that implements an interface // that describes an object that the code I am testing relies on. -type MyMockedObject struct{ - mock.Mock +type MyMockedObject struct { + mock.Mock } // DoSomething is a method on MyMockedObject that implements some interface @@ -142,10 +140,8 @@ type MyMockedObject struct{ // // NOTE: This method is not being tested here, code that uses this object is. func (m *MyMockedObject) DoSomething(number int) (bool, error) { - - args := m.Called(number) - return args.Bool(0), args.Error(1) - + args := m.Called(number) + return args.Bool(0), args.Error(1) } /* @@ -155,20 +151,17 @@ func (m *MyMockedObject) DoSomething(number int) (bool, error) { // TestSomething is an example of how to use our test object to // make assertions about some target code we are testing. func TestSomething(t *testing.T) { + // create an instance of our test object + testObj := new(MyMockedObject) - // create an instance of our test object - testObj := new(MyMockedObject) - - // set up expectations - testObj.On("DoSomething", 123).Return(true, nil) - - // call the code we are testing - targetFuncThatDoesSomethingWithObj(testObj) - - // assert that the expectations were met - testObj.AssertExpectations(t) + // set up expectations + testObj.On("DoSomething", 123).Return(true, nil) + // call the code we are testing + targetFuncThatDoesSomethingWithObj(testObj) + // assert that the expectations were met + testObj.AssertExpectations(t) } // TestSomethingWithPlaceholder is a second example of how to use our test object to @@ -177,45 +170,42 @@ func TestSomething(t *testing.T) { // data being passed in is normally dynamically generated and cannot be // predicted beforehand (eg. containing hashes that are time sensitive) func TestSomethingWithPlaceholder(t *testing.T) { + // create an instance of our test object + testObj := new(MyMockedObject) - // create an instance of our test object - testObj := new(MyMockedObject) - - // set up expectations with a placeholder in the argument list - testObj.On("DoSomething", mock.Anything).Return(true, nil) + // set up expectations with a placeholder in the argument list + testObj.On("DoSomething", mock.Anything).Return(true, nil) - // call the code we are testing - targetFuncThatDoesSomethingWithObj(testObj) - - // assert that the expectations were met - testObj.AssertExpectations(t) + // call the code we are testing + targetFuncThatDoesSomethingWithObj(testObj) + // assert that the expectations were met + testObj.AssertExpectations(t) } // TestSomethingElse2 is a third example that shows how you can use // the Unset method to cleanup handlers and then add new ones. func TestSomethingElse2(t *testing.T) { + // create an instance of our test object + testObj := new(MyMockedObject) - // create an instance of our test object - testObj := new(MyMockedObject) - - // set up expectations with a placeholder in the argument list - mockCall := testObj.On("DoSomething", mock.Anything).Return(true, nil) + // set up expectations with a placeholder in the argument list + mockCall := testObj.On("DoSomething", mock.Anything).Return(true, nil) - // call the code we are testing - targetFuncThatDoesSomethingWithObj(testObj) + // call the code we are testing + targetFuncThatDoesSomethingWithObj(testObj) - // assert that the expectations were met - testObj.AssertExpectations(t) + // assert that the expectations were met + testObj.AssertExpectations(t) - // remove the handler now so we can add another one that takes precedence - mockCall.Unset() + // remove the handler now so we can add another one that takes precedence + mockCall.Unset() - // return false now instead of true - testObj.On("DoSomething", mock.Anything).Return(false, nil) + // return false now instead of true + testObj.On("DoSomething", mock.Anything).Return(false, nil) - testObj.AssertExpectations(t) + testObj.AssertExpectations(t) } ``` @@ -235,35 +225,36 @@ An example suite is shown below: ```go // Basic imports import ( - "testing" - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/suite" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/suite" ) // Define the suite, and absorb the built-in basic suite // functionality from testify - including a T() method which // returns the current testing context type ExampleTestSuite struct { - suite.Suite - VariableThatShouldStartAtFive int + suite.Suite + VariableThatShouldStartAtFive int } // Make sure that VariableThatShouldStartAtFive is set to five // before each test func (suite *ExampleTestSuite) SetupTest() { - suite.VariableThatShouldStartAtFive = 5 + suite.VariableThatShouldStartAtFive = 5 } // All methods that begin with "Test" are run as tests within a // suite. func (suite *ExampleTestSuite) TestExample() { - assert.Equal(suite.T(), 5, suite.VariableThatShouldStartAtFive) + assert.Equal(suite.T(), 5, suite.VariableThatShouldStartAtFive) } // In order for 'go test' to run this suite, we need to create // a normal test function and pass our suite to suite.Run func TestExampleTestSuite(t *testing.T) { - suite.Run(t, new(ExampleTestSuite)) + suite.Run(t, new(ExampleTestSuite)) } ``` @@ -276,33 +267,34 @@ For more information on writing suites, check out the [API documentation for the ```go // Basic imports import ( - "testing" - "github.com/stretchr/testify/suite" + "testing" + + "github.com/stretchr/testify/suite" ) // Define the suite, and absorb the built-in basic suite // functionality from testify - including assertion methods. type ExampleTestSuite struct { - suite.Suite - VariableThatShouldStartAtFive int + suite.Suite + VariableThatShouldStartAtFive int } // Make sure that VariableThatShouldStartAtFive is set to five // before each test func (suite *ExampleTestSuite) SetupTest() { - suite.VariableThatShouldStartAtFive = 5 + suite.VariableThatShouldStartAtFive = 5 } // All methods that begin with "Test" are run as tests within a // suite. func (suite *ExampleTestSuite) TestExample() { - suite.Equal(suite.VariableThatShouldStartAtFive, 5) + suite.Equal(suite.VariableThatShouldStartAtFive, 5) } // In order for 'go test' to run this suite, we need to create // a normal test function and pass our suite to suite.Run func TestExampleTestSuite(t *testing.T) { - suite.Run(t, new(ExampleTestSuite)) + suite.Run(t, new(ExampleTestSuite)) } ``` @@ -329,14 +321,13 @@ Import the `testify/assert` package into your code using this template: package yours import ( - "testing" - "github.com/stretchr/testify/assert" + "testing" + + "github.com/stretchr/testify/assert" ) func TestSomething(t *testing.T) { - - assert.True(t, true, "True is true!") - + assert.True(t, true, "True is true!") } ```