diff --git a/README.md b/README.md index 34aa6d1..5c33c2a 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,9 @@ Capítulos do Curso --cap=22 --topics Exercícios Ninja: Nível 10 --cap=23 --topics Tratamento de Erro --cap=24 --topics Exercícios Ninja: Nível 11 + --cap=25 --topics Documentação + --cap=26 --topics Exercícios Ninja: Nível 12 + --cap=27 --topics Teste e Benchmarking Outline do Curso por Capítulo @@ -157,6 +160,10 @@ Outline do Curso por Capítulo --cap=21 --overview Canais --cap=22 --overview Exercícios Ninja Nível 10 --cap=23 --overview Tratamento de Erro + --cap=24 --overview Exercícios Ninja Nível 11 + --cap=25 --overview Documentação + --cap=26 --overview Exercícios Ninja Nível 12 + --cap=27 --overview Teste e Benchmarking Capítulo 1: Visão Geral do Curso @@ -485,6 +492,31 @@ Capítulo 24: Exercicios Ninja Nível 11 --na-pratica-exercicio-5 --nivel-11 Apresenta o quinto exercício prático do curso. --na-pratica-exercicio-5 --nivel-11 --resolucao Exibe a resolução do quinto exercício prático. +Capítulo 25: Documentação + --introducao Introdução + --go-doc go doc + --godoc godoc + --pkg-go-dev https://pkg.go.dev/ + --escrevendo-documentacao Escrevendo documentação + +Capítulo 26: Exercicios Ninja Nível 12 + + --na-pratica-exercicio-1 --nivel-12 Apresenta o primeiro exercício prático do curso. + --na-pratica-exercicio-1 --nivel-12 --resolucao Exibe a resolução do primeiro exercício prático. + --na-pratica-exercicio-2 --nivel-12 Apresenta o segundo exercício prático do curso. + --na-pratica-exercicio-2 --nivel-12 --resolucao Exibe a resolução do segundo exercício prático. + --na-pratica-exercicio-3 --nivel-12 Apresenta o terceiro exercício prático do curso. + --na-pratica-exercicio-3 --nivel-12 --resolucao Exibe a resolução do terceiro exercício prático. + +Capítulo 27: Teste e Benchmarking + + --introducao Introdução + --testes-em-tabelas Testes em tabelas + --testes-como-exemplo Testes como exemplo + --go-fmt-govet-golint go fmt, govet e golint + --benchmark Benchmark + --cobertura Cobertura + ``` ## Estrutura do Projeto @@ -524,6 +556,9 @@ Capítulo 24: Exercicios Ninja Nível 11 │   ├── concorrencia │   │   ├── overview.yml │   │   └── topics.go +│   ├── documentacao +│   │   ├── overview.yml +│   │   └── topics.go │   ├── exercicios_ninja_nivel_1 │   │   ├── overview.yml │   │   ├── resolution_exercises.go @@ -537,6 +572,10 @@ Capítulo 24: Exercicios Ninja Nível 11 │   │   ├── resolution_exercises.go │   │   ├── resolution_exercises_test.go │   │   └── topics.go +│   ├── exercicios_ninja_nivel_12 +│   │   ├── overview.yml +│   │   ├── resolution_exercises.go +│   │   └── topics.go │   ├── exercicios_ninja_nivel_2 │   │   ├── overview.yml │   │   ├── resolution_exercises.go @@ -594,6 +633,9 @@ Capítulo 24: Exercicios Ninja Nível 11 │   ├── structs │   │   ├── overview.yml │   │   └── topics.go +│   ├── teste_benchmarking +│   │   ├── overview.yml +│   │   └── topics.go │   ├── tratamento_de_erro │   │   ├── overview.yml │   │   └── topics.go @@ -619,14 +661,10 @@ Capítulo 24: Exercicios Ninja Nível 11 │   └── overview.go └── tree.log -38 directories, 90 files +41 directories, 97 files ``` -## Documentação Técnica - -[`pkg/format/questionnaire.go`](docs/questionarie.md) - ## Licença Este projeto é licenciado sob a licença MIT. Consulte o arquivo [LICENSE](LICENSE) para obter detalhes. diff --git a/docs/questionarie.md b/docs/questionarie.md deleted file mode 100644 index f04399e..0000000 --- a/docs/questionarie.md +++ /dev/null @@ -1,82 +0,0 @@ -# [Questionnaire](../pkg/format/questionnaire.go) - -This Go package creates, collects, and validates a questionnaire. It defined some interfaces and structures to manage the questionnaire and answers. - -## Interfaces - -### [1. CreateQuestionarie](../pkg/format/questionnaire.go#L10) - -- Is defined as the method `Create` that will create a questionnaire from a slice of the questionnaire. -- Returns a Slice of the Questionnaire. - -### [2. CollectAnswers](../pkg/format/questionnaire.go#L18) - -- Is defined as the method `Collect` that will collect the answers from a questionnaire. -- Receive a slice of a questionnaire and return a slice of Answers and an error. - -### [3. ValidateAnswers](../pkg/format/questionnaire.go#L26) - -- Is defined as the method `Validate` that will validate the answers from a questionnaire. -- Receive two slices of Answers (user answers and correct answers). - -## Structures - -### [1. Questionnaire](../pkg/format/questionnaire.go#L34) - -- Represents a question in a test with options for answers -- Fields: - - `Number`: The number of the question. - - `Question`: The question. - - `Options`: The options of the question. - -### [2. Answer](../pkg/format/questionnaire.go#L41) - -- Represents an answer to a question, storing the answer of the user and status. -- Fields: - - `Number`: The number of the question. - - `Answer`: The answer of the user. - - `Status`: The status of the answer (correct or incorrect). - -## [3. QuestionnaireService](../pkg/format/questionnaire.go#L48) - -- Implements the interface `CreateQuestionnaire` through the method `Create`. -- Method `Create`: - - Receives a slice of questions and returns a slice of the questionnaire. - - Iterated over the slice of the questionnaire and added a question and options to the slice test. - -### [4. AnswerService](../pkg/format/questionnaire.go#L64) - -- Implements the interface `CollectAnswers` and `ValidateAnswers` through the methods `Collect` and `Validate`. -- [Method `Collect`](../pkg/format/questionnaire.go#L68): - - Receives a slice of the questionnaire and returns a slice of answers and an error. - - Create a questionnaire using `QuestionnaireService`. - - Iterated the questionnaire and collected the answers from the user. - - Validate the answers using the function `validateOption`. -- [Method `Validate`](../pkg/format/questionnaire.go#L94): - - Receives two slices of answers (user answers and correct answers). - - Iterated the answers and validated the answers checking if the answer was correct or incorrect. - - Calculate the score of the user and return the score. - -## Auxiliary Functions - -### [1. validateOption](../pkg/format/questionnaire.go#L129) - -- Checking if the user's answer is valid to answer the question. -- Receives an answer from the user and validates if the answer is a string -- Returns `true` if the answer is between the valid options otherwise returns `false`. - -## How it works - -### 1. Creates Questionnaire - -- The questionnaire is created when using the method `Create` from `QuestionnaireService` - -### 2. Collect the Answers - -- The answers are collected when using the method `Collect` from `AnswerService` -- The answers are validated using the function `validateOption` - -### 3. Validate the Answers - -- The answers are validated when using the method `Validate` from `AnswerService` -- The results show up including the score count of answers and correct percentage. diff --git a/internal/chapter/chapter.go b/internal/chapter/chapter.go index d98b67f..59c676d 100644 --- a/internal/chapter/chapter.go +++ b/internal/chapter/chapter.go @@ -29,6 +29,7 @@ import ( "github.com/fabianoflorentino/aprendago/internal/ponteiros" "github.com/fabianoflorentino/aprendago/internal/seu_ambiente_de_desenvolvimento" "github.com/fabianoflorentino/aprendago/internal/structs" + "github.com/fabianoflorentino/aprendago/internal/teste_benchmarking" "github.com/fabianoflorentino/aprendago/internal/tratamento_de_erro" "github.com/fabianoflorentino/aprendago/internal/variaveis_valores_tipos" "github.com/fabianoflorentino/aprendago/internal/visao_geral_do_curso" @@ -66,5 +67,6 @@ func New() []func() { exercicios_ninja_nivel_11.ExerciciosNinjaNivel11, documentacao.Documentacao, exercicios_ninja_nivel_12.ExerciciosNinjaNivel12, + teste_benchmarking.TesteEBenchmarking, } } diff --git a/internal/documentacao/topics.go b/internal/documentacao/topics.go index 69605ee..da8ed58 100644 --- a/internal/documentacao/topics.go +++ b/internal/documentacao/topics.go @@ -1,3 +1,7 @@ +// Package documentacao provides functionalities to handle documentation topics +// for the "aprendago" project. It includes functions to display documentation +// sections, generate menu options for documentation topics, and print help +// information related to documentation. package documentacao import ( @@ -6,10 +10,14 @@ import ( "github.com/fabianoflorentino/aprendago/pkg/format" ) +// rootDir represents the root directory for documentation files within the project. const ( rootDir = "internal/documentacao" ) +// Package documentacao provides functions to execute and display various sections +// related to Go documentation. It includes topics such as introduction to documentation, +// usage of go doc, godoc, and pkg.go.dev, as well as writing documentation. func Documentacao() { fmt.Printf("\n\nCapítulo 25: Documentação\n") @@ -20,9 +28,15 @@ func Documentacao() { executeSections("Escrevendo documentação") } +// Package documentacao provides functionalities related to documentation topics in Go. +// It includes a menu with various documentation options and their respective execution functions. + +// MenuDocumentacao returns a slice of MenuOptions containing different documentation topics +// and their associated execution functions. Each option is represented by a string and +// an ExecFunc that executes the corresponding section. func MenuDocumentacao([]string) []format.MenuOptions { return []format.MenuOptions{ - {Options: "--introducao", ExecFunc: func() { executeSections("Introdução") }}, + {Options: "--introducao-documentacao", ExecFunc: func() { executeSections("Introdução") }}, {Options: "--go-doc", ExecFunc: func() { executeSections("go doc") }}, {Options: "--godoc", ExecFunc: func() { executeSections("godoc") }}, {Options: "--pkg-go-dev", ExecFunc: func() { executeSections("https://pkg.go.dev/") }}, @@ -30,6 +44,18 @@ func MenuDocumentacao([]string) []format.MenuOptions { } } +// HelpMeDocumentacao provides a list of documentation topics and their descriptions. +// It prints a formatted help message for Chapter 25: Documentation. +// +// The topics include: +// - Introdução: Introduction to the topic +// - go doc: Information about the 'go doc' command +// - godoc: Information about the 'godoc' command +// - https://pkg.go.dev/: Link to the Go package documentation website +// - Escrevendo documentação: Tips on writing documentation +// +// This function is part of the 'documentacao' package, which contains utilities and helpers +// for generating and managing documentation in Go projects. func HelpMeDocumentacao() { hlp := []format.HelpMe{ {Flag: "--introducao", Description: "Introdução"}, @@ -43,6 +69,9 @@ func HelpMeDocumentacao() { format.PrintHelpMe(hlp) } +// executeSections formats and processes a given section of documentation. +// It takes a section name as a string and uses the FormatSection function +// from the format package to apply formatting to the section within the root directory. func executeSections(section string) { format.FormatSection(rootDir, section) } diff --git a/internal/menu/capitulo_options.go b/internal/menu/capitulo_options.go index eb4b9e5..9eedbe7 100644 --- a/internal/menu/capitulo_options.go +++ b/internal/menu/capitulo_options.go @@ -28,6 +28,7 @@ import ( "github.com/fabianoflorentino/aprendago/internal/ponteiros" "github.com/fabianoflorentino/aprendago/internal/seu_ambiente_de_desenvolvimento" "github.com/fabianoflorentino/aprendago/internal/structs" + "github.com/fabianoflorentino/aprendago/internal/teste_benchmarking" "github.com/fabianoflorentino/aprendago/internal/tratamento_de_erro" "github.com/fabianoflorentino/aprendago/internal/variaveis_valores_tipos" "github.com/fabianoflorentino/aprendago/internal/visao_geral_do_curso" @@ -64,6 +65,7 @@ func MenuCapituloOptions([]string) []format.MenuOptions { {Options: "--cap=24 --topics", ExecFunc: func() { exercicios_ninja_nivel_11.HelpMeExerciciosNinjaNivel11() }}, {Options: "--cap=25 --topics", ExecFunc: func() { documentacao.HelpMeDocumentacao() }}, {Options: "--cap=26 --topics", ExecFunc: func() { exercicios_ninja_nivel_12.HelpMeExerciciosNinjaNivel12() }}, + {Options: "--cap=27 --topics", ExecFunc: func() { teste_benchmarking.HelpMeTesteEBenchmarking() }}, } } @@ -100,6 +102,7 @@ func HelpMeCapituloOptions() { {Flag: "--cap=24 --topics", Description: "Exercícios Ninja: Nível 11"}, {Flag: "--cap=25 --topics", Description: "Documentação"}, {Flag: "--cap=26 --topics", Description: "Exercícios Ninja: Nível 12"}, + {Flag: "--cap=27 --topics", Description: "Teste e Benchmarking"}, } fmt.Println("Capítulos do Curso") diff --git a/internal/menu/capitulo_outline.go b/internal/menu/capitulo_outline.go index c1512b5..6362f67 100644 --- a/internal/menu/capitulo_outline.go +++ b/internal/menu/capitulo_outline.go @@ -28,6 +28,7 @@ import ( "github.com/fabianoflorentino/aprendago/internal/ponteiros" "github.com/fabianoflorentino/aprendago/internal/seu_ambiente_de_desenvolvimento" "github.com/fabianoflorentino/aprendago/internal/structs" + "github.com/fabianoflorentino/aprendago/internal/teste_benchmarking" "github.com/fabianoflorentino/aprendago/internal/tratamento_de_erro" "github.com/fabianoflorentino/aprendago/internal/variaveis_valores_tipos" "github.com/fabianoflorentino/aprendago/internal/visao_geral_do_curso" @@ -66,6 +67,7 @@ func MenuCapituloOutline([]string) []format.MenuOptions { {Options: "--cap=24 --overview", ExecFunc: func() { exercicios_ninja_nivel_11.ExerciciosNinjaNivel11() }}, {Options: "--cap=25 --overview", ExecFunc: func() { documentacao.Documentacao() }}, {Options: "--cap=26 --overview", ExecFunc: func() { exercicios_ninja_nivel_12.ExerciciosNinjaNivel12() }}, + {Options: "--cap=27 --overview", ExecFunc: func() { teste_benchmarking.TesteEBenchmarking() }}, } } @@ -100,6 +102,7 @@ func HelpMeCapituloOutline() { {Flag: "--cap=24 --overview", Description: "Exercícios Ninja Nível 11"}, {Flag: "--cap=25 --overview", Description: "Documentação"}, {Flag: "--cap=26 --overview", Description: "Exercícios Ninja Nível 12"}, + {Flag: "--cap=27 --overview", Description: "Teste e Benchmarking"}, } fmt.Printf("\nOutline do Curso por Capítulo\n") diff --git a/internal/menu/helpme.go b/internal/menu/helpme.go index 6ede735..ae6196e 100644 --- a/internal/menu/helpme.go +++ b/internal/menu/helpme.go @@ -29,6 +29,7 @@ import ( "github.com/fabianoflorentino/aprendago/internal/ponteiros" "github.com/fabianoflorentino/aprendago/internal/seu_ambiente_de_desenvolvimento" "github.com/fabianoflorentino/aprendago/internal/structs" + "github.com/fabianoflorentino/aprendago/internal/teste_benchmarking" "github.com/fabianoflorentino/aprendago/internal/tratamento_de_erro" "github.com/fabianoflorentino/aprendago/internal/variaveis_valores_tipos" "github.com/fabianoflorentino/aprendago/internal/visao_geral_do_curso" @@ -84,4 +85,5 @@ func HelpMe() { exercicios_ninja_nivel_11.HelpMeExerciciosNinjaNivel11() documentacao.HelpMeDocumentacao() exercicios_ninja_nivel_12.HelpMeExerciciosNinjaNivel12() + teste_benchmarking.HelpMeTesteEBenchmarking() } diff --git a/internal/menu/options.go b/internal/menu/options.go index d9d8a84..6b80c94 100644 --- a/internal/menu/options.go +++ b/internal/menu/options.go @@ -51,6 +51,7 @@ import ( "github.com/fabianoflorentino/aprendago/internal/ponteiros" "github.com/fabianoflorentino/aprendago/internal/seu_ambiente_de_desenvolvimento" "github.com/fabianoflorentino/aprendago/internal/structs" + "github.com/fabianoflorentino/aprendago/internal/teste_benchmarking" "github.com/fabianoflorentino/aprendago/internal/tratamento_de_erro" "github.com/fabianoflorentino/aprendago/internal/variaveis_valores_tipos" "github.com/fabianoflorentino/aprendago/internal/visao_geral_do_curso" @@ -98,6 +99,7 @@ func Options(args []string) { exercicios_ninja_nivel_11.MenuExerciciosNinjaNivel11(args), documentacao.MenuDocumentacao(args), exercicios_ninja_nivel_12.MenuExerciciosNinjaNivel12(args), + teste_benchmarking.MenuTesteEBenchmarking(args), ) } diff --git a/internal/teste_benchmarking/overview.yml b/internal/teste_benchmarking/overview.yml new file mode 100644 index 0000000..6a0d413 --- /dev/null +++ b/internal/teste_benchmarking/overview.yml @@ -0,0 +1,63 @@ +--- +description: + name: "Capítulo 27: Teste de Benchmarking" + sections: + - title: "Introdução" + text: | + - Testes devem: + - ficar num arquivo cuja terminação seja _test.go + - ficar na mesma package que o código a ser testado + - ficar em funções com nome "func TestNome(*testing.T)" + - Para rodar os testes: + - go test + - go test -v + - Para falhas, utilizamos t.Error(), onde a maneira idiomática é algo do tipo "expected: x. got: y." + - Código: https://github.com/ellenkorbes/aprendago/tree/master/c%C3%B3digo/27_testes-e-benchmarking/01_introducao + + - title: Testes em tabelas + text: | + - Podemos escrever testes em série para testar variedades de situações. + - Exemplo: + - struct test, fields: data []int, answer int + - tests := []test{[]int{}, int} + - range tests + + - title: Testes como exemplo + text: | + - Outra maneira é fazer testes como exemplos. + - Estes exemplos são os mesmos que aparecem na documentação. + - Para exemplos o formato é "func ExampleFuncao()" + - Deve haver um comentário "// Output: resultado", que é o que será testado + - Para visualizar seu exemplo na documentação, fazemos o de sempre: + - godoc -http :8080 + - Tanto para testes quanto para exemplos podemos utilizar: go test ./... + - Mais: https://blog.golang.org/examples + + - title: go fmt, govet e golint + text: | + - gofmt: formata o código + - go vet: correctness → procura constructs suspeitos + - golint: suggestions → procura coding style ruim + + - title: Benchmark + text: | + - Benchmarks nos permitem testar a velocidade ou performance do nosso código. + - Na prática: + - Arquivo: _test.go + - BET: Testes, Exemplos e... + - func BenchmarkFunc (b *testing.B) { for i := 0; i < b.N; i++ { ... } } + - go test -bench . ← todos + - go test -bench Func ← somente Func + - go help testflag + - Código: https://github.com/ellenkorbes/aprendago/tree/master/c%C3%B3digo/27_testes-e-benchmarking/benchtest + + - title: Cobertura + text: | + - "Cobertura" em se tratando de testes se refere a quanto do seu código, percentualmente, está sendo testado. (E antes que alguem fique neurótico querendo 100%: em geral, 70-80% tá ótimo.) + - A flag -cover faz a análise de cobertura do nosso código. + - Podemos utilizar a flag -coverprofile para salvar a análise de cobertura em um arquivo. + - Na prática: + - go test -cover + - go test -coverprofile c.out + - go tool cover -html=c.out ← abre no browser + - go tool cover -h ← para mais detalhes diff --git a/internal/teste_benchmarking/topics.go b/internal/teste_benchmarking/topics.go new file mode 100644 index 0000000..103ae8a --- /dev/null +++ b/internal/teste_benchmarking/topics.go @@ -0,0 +1,70 @@ +// Package teste_benchmarking provides functionalities to demonstrate and execute +// various testing and benchmarking techniques in Go. It includes sections on +// introduction to testing, table-driven tests, example-based tests, code formatting +// and linting tools (go fmt, govet, golint), benchmarking, and code coverage. +// The package also offers menu options and help descriptions for each section. +package teste_benchmarking + +import ( + "fmt" + + "github.com/fabianoflorentino/aprendago/pkg/format" +) + +// rootDir represents the relative path to the directory where benchmarking tests are located. +const ( + rootDir = "internal/teste_benchmarking" +) + +// TesteEBenchmarking prints the title of Chapter 27 and executes a series of sections +// related to testing and benchmarking in Go. Each section is executed by calling the +// executeSections function with the section name as an argument. +func TesteEBenchmarking() { + fmt.Printf("\n\nCapítulo 27: Teste e Benchmarking\n") + + executeSections("Introdução") + executeSections("Testes em tabelas") + executeSections("Testes como exemplo") + executeSections("go fmt, govet e golint") + executeSections("Benchmark") + executeSections("Cobertura") +} + +// MenuTesteEBenchmarking returns a slice of MenuOptions, each representing a different +// testing and benchmarking topic. Each MenuOption contains an option string and an +// associated function to execute the corresponding section. The available options are: +// --introducao-testes-benchmarking, --testes-em-tabelas, --testes-como-exemplo, --go-fmt-govet-golint, +// --benchmark, and --cobertura. +func MenuTesteEBenchmarking([]string) []format.MenuOptions { + return []format.MenuOptions{ + {Options: "--introducao-testes-benchmarking", ExecFunc: func() { executeSections("Introdução") }}, + {Options: "--testes-em-tabelas", ExecFunc: func() { executeSections("Testes em tabelas") }}, + {Options: "--testes-como-exemplo", ExecFunc: func() { executeSections("Testes como exemplo") }}, + {Options: "--go-fmt-govet-golint", ExecFunc: func() { executeSections("go fmt, govet e golint") }}, + {Options: "--benchmark", ExecFunc: func() { executeSections("Benchmark") }}, + {Options: "--cobertura", ExecFunc: func() { executeSections("Cobertura") }}, + } +} + +// HelpMeTesteEBenchmarking prints a help message for chapter 27: Testing and Benchmarking. +// It provides a list of flags and their descriptions related to various testing and benchmarking topics. +func HelpMeTesteEBenchmarking() { + hlp := []format.HelpMe{ + {Flag: "--introducao", Description: "Introdução"}, + {Flag: "--testes-em-tabelas", Description: "Testes em tabelas"}, + {Flag: "--testes-como-exemplo", Description: "Testes como exemplo"}, + {Flag: "--go-fmt-govet-golint", Description: "go fmt, govet e golint"}, + {Flag: "--benchmark", Description: "Benchmark"}, + {Flag: "--cobertura", Description: "Cobertura"}, + } + + fmt.Printf("\nCapítulo 27: Teste e Benchmarking\n") + format.PrintHelpMe(hlp) +} + +// executeSections formats and processes a given section of the project. +// It takes a section name as a string parameter and applies formatting +// to that section using the FormatSection function from the format package. +func executeSections(section string) { + format.FormatSection(rootDir, section) +}