go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/starlark/docgen/docstring/docstring_test.go (about)

     1  // Copyright 2019 The LUCI Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package docstring
    16  
    17  import (
    18  	"strings"
    19  	"testing"
    20  
    21  	. "github.com/smartystreets/goconvey/convey"
    22  )
    23  
    24  func TestParse(t *testing.T) {
    25  	t.Parallel()
    26  
    27  	Convey("Works", t, func() {
    28  		out := Parse(`An ACL entry: assigns given role (or roles) to given individuals or groups.
    29  
    30    Specifying an empty ACL entry is allowed. It is ignored everywhere. Useful for
    31    things like:
    32  
    33        luci.project(...)
    34  
    35  
    36    Args:
    37      roles :   a single role (as acl.role) or a list of roles to assign,
    38          blah-blah multiline.
    39  
    40      groups: a single group name or a list of groups to assign the role to.
    41      stuff: line1
    42        line2
    43        line3
    44      users: a single user email or a list of emails to assign the role to.
    45  
    46  
    47      empty:
    48  
    49  
    50    Returns:
    51      acl.entry struct, consider it opaque.
    52      Multiline.
    53  
    54    Note:
    55      blah-blah.
    56  
    57    Empty:
    58  `)
    59  
    60  		So(out.Description, ShouldResemble, strings.Join([]string{
    61  			"An ACL entry: assigns given role (or roles) to given individuals or groups.",
    62  			"",
    63  			"Specifying an empty ACL entry is allowed. It is ignored everywhere. Useful for",
    64  			"things like:",
    65  			"",
    66  			"    luci.project(...)",
    67  		}, "\n"))
    68  
    69  		So(out.Fields, ShouldResemble, []FieldsBlock{
    70  			{
    71  				Title: "Args",
    72  				Fields: []Field{
    73  					{"roles", "a single role (as acl.role) or a list of roles to assign, blah-blah multiline."},
    74  					{"groups", "a single group name or a list of groups to assign the role to."},
    75  					{"stuff", "line1 line2 line3"},
    76  					{"users", "a single user email or a list of emails to assign the role to."},
    77  					{"empty", ""},
    78  				},
    79  			},
    80  		})
    81  
    82  		So(out.Remarks, ShouldResemble, []RemarkBlock{
    83  			{"Returns", "acl.entry struct, consider it opaque.\nMultiline."},
    84  			{"Note", "blah-blah."},
    85  			{"Empty", ""},
    86  		})
    87  	})
    88  }
    89  
    90  func TestNormalizedLines(t *testing.T) {
    91  	t.Parallel()
    92  
    93  	Convey("Empty", t, func() {
    94  		So(normalizedLines("  \n\n\t\t\n  "), ShouldHaveLength, 0)
    95  	})
    96  
    97  	Convey("One line and some space", t, func() {
    98  		So(normalizedLines("  \n\n  Blah   \n\t\t\n  \n"), ShouldResemble, []string{"Blah"})
    99  	})
   100  
   101  	Convey("Deindents", t, func() {
   102  		So(normalizedLines(`First paragraph,
   103  		perhaps multiline.
   104  
   105  		Second paragraph.
   106  
   107  			Deeper indentation.
   108  
   109  		Third paragraph.
   110  		`), ShouldResemble,
   111  			[]string{
   112  				"First paragraph,",
   113  				"perhaps multiline.",
   114  				"",
   115  				"Second paragraph.",
   116  				"",
   117  				"\tDeeper indentation.",
   118  				"",
   119  				"Third paragraph.",
   120  			})
   121  	})
   122  }
   123  
   124  func TestDeindent(t *testing.T) {
   125  	t.Parallel()
   126  
   127  	Convey("Space only", t, func() {
   128  		So(
   129  			deindent([]string{"  ", " \t\t  \t", ""}),
   130  			ShouldResemble,
   131  			[]string{"", "", ""},
   132  		)
   133  	})
   134  
   135  	Convey("Nothing to deindent", t, func() {
   136  		So(
   137  			deindent([]string{"  ", "a  ", "b", "  "}),
   138  			ShouldResemble,
   139  			[]string{"", "a  ", "b", ""},
   140  		)
   141  	})
   142  
   143  	Convey("Deindention works", t, func() {
   144  		So(
   145  			deindent([]string{"   ", "", "  a", "  b", "    c"}),
   146  			ShouldResemble,
   147  			[]string{"", "", "a", "b", "  c"},
   148  		)
   149  	})
   150  
   151  	Convey("Works with tabs too", t, func() {
   152  		So(
   153  			deindent([]string{"\t\t", "", "\ta", "\tb", "\t\tc"}),
   154  			ShouldResemble,
   155  			[]string{"", "", "a", "b", "\tc"},
   156  		)
   157  	})
   158  }