A Go library for generating test data, allowing for the simple and efficient creation of mocks for entities.
Mocaí is an open-source Go library designed to simplify the generation of realistic mock data for entities such as Person, Address, Phone, Company, CPF, CNPJ, Certificates, National ID (RG), and Voter Registration. The goal is to make development and testing more efficient by providing random yet consistent data that simulates real-world scenarios in a practical and reliable way.
The name Mocaí is a tribute to the Brazilian initiative behind the library. It originated from the combination of "mock" (simulation or fake data) with "açaí," a typical fruit from the Brazilian Amazon, known for its energy and versatility. Just as açaí is essential for many Brazilians, Mocaí aims to be an essential tool for developers who need efficient and high-quality test data. 🇧🇷
- Random Data Generation: Generate mocks for entities with varied and realistic data (Person, Address, Phone, Company, CPF, CNPJ, Certificates, National ID, Voter Registration, and more).
- Consistency: Ensures generated data is consistent and suitable for testing.
- Ease of Use: Simple and intuitive API for quick integration.
- Extensibility: Easily add new entities or languages. The architecture is modular and ready for expansion.
- Open Source: Collaborate, suggest improvements, and contribute to the growth of the library.
- Person (with gender, age, CPF)
- Gender (standalone generation)
- Address (street, number, city, state, UF, ZIP)
- Phone (area code, number)
- Company (name, CNPJ)
- CPF (Brazilian individual taxpayer registry)
- Certificates (Birth, Marriage, Death)
- National ID (RG)
- Voter Registration (Título de Eleitor)
- ptbr (Brazilian Portuguese) is currently supported. The structure allows for easy addition of new languages in the future.
- Productivity: Reduce the time spent creating test data.
- Quality: Improve test coverage and effectiveness with realistic data.
- Flexibility: Adapt mocks to your project's specific needs.
- Community: Be part of an open-source community that values collaboration and innovation.
- Go 1.23.4 or higher
To start using Mocaí, install the library with:
go get github.com/brazzcore/mocaiImport the library and generate mocks using the Mocker struct methods:
package main
import (
"fmt"
"log"
"github.com/brazzcore/mocai/pkg/mocai"
)
func main() {
// Create a Mocker instance for Brazilian Portuguese
mocker := mocai.NewMocker(
mocai.WithLanguage("ptbr"),
mocai.WithFormatted(true),
)
// Generate a mock address
address, err := mocker.NewAddress()
if err != nil {
log.Fatal(err)
}
fmt.Printf("Address: %s, %d - %s, %s (%s) - %s\n", address.Street, address.Number, address.City, address.State, address.UF, address.ZIP)
// Generate a mock person
person, err := mocker.NewPerson()
if err != nil {
log.Fatal(err)
}
fmt.Printf("Person: %s %s, Gender: %s, Age: %d, CPF: %s\n", person.FirstNameMale, person.LastName, person.Gender.Identity, person.Age, person.CPF.Number)
// Generate a mock company
company, err := mocker.NewCompany()
if err != nil {
log.Fatal(err)
}
fmt.Printf("Company: %s, CNPJ: %s\n", company.BrazilianCompany.Name, company.BrazilianCompany.CNPJ)
}Error messages are localized where translation keys are available. When an error occurs (e.g., invalid data, unsupported language, or generation failure), the error message will be presented in the language configured for the Mocker instance, if a translation exists. In some cases, fallback or hardcoded errors may occur if translation coverage is incomplete.
You do not need to perform any extra steps for error localization — Mocai handles this automatically for all supported languages where translation keys are present.
Note: Each call to a method like
NewPerson()orNewAddress()generates a new mock with random data. TheMockerinstance is immutable regarding its configuration (language, formatting, random source).
Currently, only "ptbr" is implemented. To support other languages, contribute with new translation and mock data files.
The WithFormatted option controls whether documents like CPF/CNPJ are returned formatted (e.g., 123.456.789-00) or as plain numbers (12345678900).
The MockGenerator interface defines the contract for generating mock data. Use it for dependency injection in your tests:
func CreateUser(generator mocai.MockGenerator) (*User, error) {
person, err := generator.NewPerson()
if err != nil {
return nil, err
}
return &User{Name: person.FirstNameMale + " " + person.LastName}, nil
}You can inject custom providers for Address, Person, and Company to integrate with external APIs or databases:
mocker := mocai.NewMocker(
mocai.WithLanguage("ptbr"),
mocai.WithAddressProvider(myCustomAddressProvider),
mocai.WithPersonProvider(myCustomPersonProvider),
mocai.WithCompanyProvider(myCustomCompanyProvider),
)Use WithRandSource to provide a custom random source for reproducible test data:
rnd := translations.NewSafeRandSource(myFixedRand)
mocker := mocai.NewMocker(
mocai.WithLanguage("ptbr"),
mocai.WithRandSource(rnd),
)The examples folder contains usage samples:
mocker/: Example using the main entry pointmocai.NewMocker(opts ...Option)with functional options to generate mocks in a fluent and simplified way.
To run an example:
cd examples/mocker
go run main.goTo run all tests:
go test ./...Mocaí is an open-source project, and your contribution is very welcome! Whether it's reporting bugs, suggesting new features, or submitting pull requests, your participation helps improve the library for everyone.
- Report Issues: Found a bug or have a suggestion? Open an issue.
- Submit Pull Requests: Follow the contribution guidelines and submit your improvements. Always run tests before submitting.
- Discuss Ideas: Join discussions and share your ideas for the project.
- Follow the project's coding standards.
- Add tests for new features.
- If necessary, document your changes in the README.md.
Mocaí is distributed under the MIT License.
Welcome to the project, and feel free to explore, use, and contribute!
Join the Mocai server on Discord: Click here and join us!