reflections_cats_test.go

package reflect_cats_test import ( "encoding/json" "net/url" "reflect" "testing" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) // Blog post here: https://blog.carbonfive.com/2020/04/07/reflections-in-go-for-cats/ // As stated in my blog post, to make this more palatable, // I've contrived a slightly different set of requirements from // what I had to implement. // First, spend a few minutes reading over the implementations and // interface at the bottom of this gist. // We will receive bytes that we expect to convert to a Pet //(see implementations at the bottom of this file), but we don't know in // advance what Type of Pet it is. We need to make an empty <someType> //struct and call Pet.Adopt() on it. // // The deserialization function signature is: // `func(t reflect.Type, data []byte) Pet` // func TestHowToUseReflections(t *testing.T) { // First we'll look at reflections generally. Say we have an initialized Cat: cat := Cat{} // Let's look at what TypeOf gives us. This is the parameter // type we must use in our deserialization function. catPtrType := reflect.TypeOf(&cat) // returns a reflect.Type assert.Equal(t, "*reflect_cats_test.Cat", catPtrType.String()) // Why aren't we looking at reflect.TypeOf(cat)? // Look at the methods of Cat which fulfill the Pet interface: // func (f *Cat) IsVaccinated() bool // These functions take pointer receivers. We must call the Pet // interface functions on a pointer to a Cat, and the Registrar // expects pointer types. // You could, if you want, not use pointer receivers, but this // discussion could be its own blog post. Experiment with it // in a separate test of your own. // Continuing, if we want to instantiate a struct via its type, we should // use reflect.New somehow. godoc says, "New returns a Value // representing a pointer to a new zero value for the specified type." // That is, the returned Value's Type is PtrTo(typ) aCatPtrTypeVal := reflect.New(catPtrType) // We now have a Value that is a pointer to a pointer. Illustrative, // but not very useful; it's going the opposite direction of // what we want, which is an empty struct. assert.Equal(t, "<**reflect_cats_test.Cat Value>", aCatPtrTypeVal.String()) // Let's get back to the thing we want to initialize -- a Cat. // For pointers, Elem() and Indirect() return the same thing: aCatPtrVal := reflect.Indirect(aCatPtrTypeVal) // this should be a *Cat assert.Equal(t, aCatPtrVal, aCatPtrTypeVal.Elem()) // yes, it is a *Cat // We now have a reflect.Value containing a pointer to a Cat: assert.Equal(t, "<*reflect_cats_test.Cat Value>", aCatPtrVal.String()) // reflect.New(thingType) creates a reflect.Value, containing a pointer to // the zero-value version of a thing of Type thingType. // // If thingType is a Kind of pointer, it creates a real pointer to nil, i.e., // &(nil) // NOT a real pointer to a Zero value of what typeThing points to, i.e., // NOT &(&thing{}) assert.False(t, aCatPtrTypeVal.IsNil()) // it's a non-nil address assert.True(t, aCatPtrTypeVal.Elem().IsNil()) // that points to a nil address for a Cat // If what you want is &(&thing{}), you must call Set, using reflect.New on // catPtrType.Elem(), where catPtrType.Elem points to a type // that the pointer points to. // Here we set aCatPtrVal to the Value of a pointer to an // empty/zero-value Cat. // To get the empty Cat struct from this, we call Value.Elem, // which gives us the child Value that the pointer contains. // So, catPtrType is a TypeOf *Cat, and catPtrType.Elem() gives us a TypeOf Cat catType := catPtrType.Elem() // New initializes an empty struct. Note reflect.New returns a pointer // to a -- Value -- of the provided type. aCatPtrVal2 := reflect.New(catType) // You can do the same by calling Set on an existing pointer: aCatPtrVal.Set(reflect.New(catType)) assert.NotEqual(t, aCatPtrVal, aCatPtrVal2) // The two addresses are different, // but the struct values are the same. We check the Cat struct fields by // calling aCatPtrVal.Elem() : assert.Equal(t, "", aCatPtrVal.Elem().FieldByName("Name").String()) assert.Equal(t, "", aCatPtrVal2.Elem().FieldByName("Name").String()) assert.Equal(t, "<bool Value>", aCatPtrVal.Elem().FieldByName("Vaccinated").String()) assert.Equal(t, "<bool Value>", aCatPtrVal2.Elem().FieldByName("Vaccinated").String()) // Note we can't ask about struct fields that don't exist: assert.Equal(t, "<invalid Value>", aCatPtrVal.Elem().FieldByName("Nonexistentfield").String()) // Then we call Value.Interface to give us thing itself // as a reflect.Value. Here is what we wanted in the first place: // an empty Cat struct. Well this certainly a roundabout way to get there. assert.Equal(t, cat, aCatPtrVal.Elem().Interface()) // This checks the same thing as above: assert.True(t, aCatPtrVal2.Elem().IsZero()) // Let's see if we can call Pet interface funcs. aPet, ok := aCatPtrVal2.Interface().(Pet) require.True(t, ok) // verify the cast worked require.NotNil(t, aPet) // otherwise the linter warns we didn't do a nil check // Now we are getting somewhere. // make a JSON-serialized Cat and check that we can deserialize it. shelterPet := `{"name":"Lily","vaccinated":true}` require.NoError(t, aPet.Adopt([]byte(shelterPet))) // Try calling more interface functions assert.True(t, aPet.IsVaccinated()) assert.Equal(t, "Lily", aPet.PetName()) // woo! our deserialize worked! // Can we play some more? Let's cast to Cat so we can directly // examine Cat things. aCat, ok := aCatPtrVal.Interface().(Cat) typeOfACatPtrValInterface := reflect.TypeOf(aCat) // ^^ What is this thing's type? // It's a Cat. assert.Equal(t, "reflect_cats_test.Cat", typeOfACatPtrValInterface.String()) // We can now call Adopt and prove that it worked: require.NoError(t, aCat.Adopt([]byte(shelterPet))) // We can also now look at Cat.Cat-specific fields and funcs: assert.Equal(t, "Lily", aCat.Name) assert.Equal(t, "meow!", aCat.Sound()) } // Now that we've done some exploratory playing around, // implement what we have learned. func TestImplementation(t *testing.T) { catPtrType := reflect.TypeOf(&Cat{}) petStream := `{"name":"Freddie","type":"Felis Catus"}` // our function takes a type, and some data, and combines // these two to return a Pet, if possible. // if it's not possible, it returns nil. AdoptFunc := func(incomingType reflect.Type, data []byte) Pet { // incomingType is expected to be a pointer Kind. You can do a safety check: if incomingType.Kind() != reflect.Ptr { return nil } // From godoc: "Elem returns the value that the interface v // contains or that the pointer v points to." // So here reflect.New(incomingType.Elem()) is the same as saying // // vStructPtr := reflect.ValueOf(&Cat{}) // // Since this function doesn't know at compile time what // to deserialize, we use incomingType.Elem() vStructPtr := reflect.New(incomingType.Elem()) // vStructPtr.Interface() gives us a *Cat. Check that // it casts to a Pet interface. pet, ok := vStructPtr.Interface().(Pet) if !ok { return nil } if err := pet.Adopt(data); err != nil { return nil } return pet } res := AdoptFunc(catPtrType, []byte(petStream)) require.NotNil(t, res) // Verify the Pet functions' outputs assert.Equal(t, "Freddie", res.PetName()) assert.Equal(t, "Felis Catus", res.Species()) assert.False(t, res.IsVaccinated()) // verify that we can send AdoptFunc bad input without // panicking. // 1. try with the wrong type, e.g. a non-pointer type. urlType := reflect.TypeOf(url.URL{}) res = AdoptFunc(urlType, []byte(petStream)) assert.Nil(t, res) // 2. try with json data that will not serialize to a Cat. res = AdoptFunc(catPtrType, []byte(`"garbage":"moregarbage"`)) assert.Nil(t, res) // 3. try with a pointer type that doesn't implement Pet, // but otherwise looks sort of like a Cat type struct. type Borked struct { Name string `json:"name"` } borkedPtrType := reflect.TypeOf(&Borked{}) res = AdoptFunc(borkedPtrType, []byte(petStream)) assert.Nil(t, res) } // There was another requirement for this story, which was to allow // registration of types with validation functions. // // We have Pets which must be registered by their owners, including a // Veterinarian that must be able to Examine the Pet and vaccinate them. // If Examine is successful, then IsVaccinated should return true. // Simulate getting a pet from a shelter by deserializing bites, // I mean, bytes, into a Pet. // The rest of this exercise is left to the reader -- make the tests pass! func TestRegistration(t *testing.T) { cv := &CatVet{} r := Registrar{} t.Run("Can register but not re-register *Cat with Registrar", func(t *testing.T) { tpf := reflect.TypeOf(&Cat{}) assert.NoError(t, r.RegisterPet(tpf, cv)) assert.Len(t, r.RegisteredPets, 1) err := r.RegisterPet(tpf, cv) assert.EqualError(t, err, "already registered Felis Catus") }) t.Run("Attempting to register a non-Pet returns an error", func(t *testing.T) { type notAPet struct{ Name string } err := r.RegisterPet(reflect.TypeOf(notAPet{ Name: "Chimpanzee" }), cv) assert.EqualError(t, err, "not a Pet") }) t.Run("returns nil, error if Pet is not a pointer", func(t *testing.T) { tf := reflect.TypeOf(Cat{}) err := r.RegisterPet(tf, cv) assert.EqualError(t, err, "reflect_cats_test.Cat is not a pointer") }) t.Run("Dog is a Pet and can be 'adopted' too", func(t *testing.T){ // If you like, make the tests pass for a Dog struct of your own // design. type Dog struct {} // var _ Pet = &Dog }) } func TestAdopt(t *testing.T) { cv := &CatVet{} r := &Registrar{} cat := &Cat{} t.Run("Registered pet is examined", func(t *testing.T) { require.NoError(t, r.RegisterPet(reflect.TypeOf(cat), cv)) petStream := `{"name":"Bili","type":"Felis Catus"}` t.Run("returns (Pet, nil) if examine succeeds.", func(t *testing.T){ pet, err := r.Adopt([]byte(petStream)) require.NoError(t, err) assert.NotNil(t, pet) assert.True(t, cat.IsVaccinated()) }) t.Run("returns error if examine fails", func(t *testing.T){ t.Fail() }) }) t.Run("can register multiple species", func(t *testing.T){ t.Fail() }) t.Run("returns nil, error if the type is not registered", func(t *testing.T) { t.Fail() }) t.Run("returns nil, error if the data cannot be unmarshaled", func(t *testing.T) { t.Fail() }) t.Run("returns nil, error if the data cannot be unmarshaled", func(t *testing.T) { t.Fail() }) } // ======== IMPLEMENTATION ======= // --- INTERFACES --- // Pet is a domesticated animal companion for humans. It can be // "adopted" via Adopt. type Pet interface { IsVaccinated() bool IsHealthy() bool Adopt([]byte) error PetName() string Species() string Vaccinate() } // --- TYPES --- // Cat implements Pet type Cat struct { // Must be exported field or JSON will not marshal/unmarshal. Name string `json:"name"` Healthy bool `json:"healthy"` Vaccinated bool `json:"vaccinated"` } // IsVaccinated returns the boolean value of f.Vaccinated func (f *Cat) IsVaccinated() bool { return f.Vaccinated } func (f *Cat) IsHealthy() bool { return f.Healthy } // Adopt deserializes data into f. func (f *Cat) Adopt(data []byte) error { return json.Unmarshal(data, f) } // PetName returns the Pet's name. func (f *Cat) PetName() string { return f.Name } // Sound func (f Cat) Sound() string { return "meow!" } func (f Cat) Vaccinate() { f.Vaccinated = true } // Species returns the string to use to register a type in the Registrar's // map of allowed types. func (f *Cat) Species() string { return "Felis Catus" } // This construct is used to ensure Cat implements the Pet interface. // If it doesn't, this doesn't compile. var _ Pet = &Cat{} // Veterinarian interface type Veterinarian interface { Examine(pet Pet) bool } type CatVet struct {} func (cv *CatVet)Examine(pet Pet) bool { if pet.IsHealthy() { pet.Vaccinate() return true } return false } // Simple registrar type Registrar struct { // RegisteredPets are mapped by their species. You could add a field in // the Veterinarian struct that indicates what species the Veterinarian // can Examine. RegisteredPets map[string]Veterinarian } // RegisterPet registers Pets to Examine, with their Veterinarian. // Registrar expects all Pet functions to have pointer receivers. // (Not Labrador receivers) Returns error if: // * the type is already registered // * the type does not implement Pet // * the type is not a pointer func (r *Registrar) RegisterPet(t reflect.Type, vet Veterinarian) error { panic("implement me") return nil } // Adopt takes bytes and attempts to convert them into a Pet // Returns nil + error if: // * the Pet type is not registered // * the pet data cannot be read // * Examine returns false func (r *Registrar) Adopt(petData []byte) (Pet, error) { panic("implement me") return nil, nil }